organization of JSON Schema files

[pvdbosch]

In GitLab by @pvdbosch on Dec 12, 2018, 19:55

Determine guidelines to organize types and JSON schema files.

Context

Current recommendation (discussions in #26 and #20):

• <domain>/<version>/<TypeName>.yaml
• <domain>/<subdomain>/<version>/<TypeName>.yaml

Examples:

• common/v1/Problem.yaml
• common/v1/HttpLink.yaml
• person/v1beta/Gender.yaml
• person/identifier/v1beta/Ssin.yaml

Originally, types were grouped into a single file per domain, e.g. a single common.yaml file with all Problem, LocalizedString, MergePatch and HttpLink types within a definitions property.
Then, it was decided to split common.yaml into separate files per main type; with the main type defined at root level and the definitions property only for subtypes so that they're more hidden i.e. private to the main type.
However, while valid JSON Schema, this doesn't appear to be valid according to the OpenAPI 2.0 SchemaObject spec, as a reference to type must not contain a definitions property.

Also, the number of YAML files to manage in this solution, might become difficult to manage.

All this reopens the discussion on how to organize JSON Schema files.

Alternatives

1. a single file per (sub)domain with all types, with version number as file name

• common/v1.yaml (with Problem, HttpLink, ... in a definitions property)
• person/v1.yaml
• person/v2.yaml
• person/identifier/v1beta.yaml

When published on the web, the URL would end in the same structure, except content negotiation would replace the YAML extension.

2. a single file per (sub)domain with all types, version number as subdirectory

• common/v1/schema.yaml
• person/v1/schema.yaml
• person/v2/schema.yaml
• person/identifier/v1beta/schema.yaml

A variant would be to use more specific names then schema.yaml; though their name would need to be roughly equivalent to the directory names then.

3. grouping of types within multiple files in a domain

• common/v1/links.yaml (with SelfLink, HttpLink, ... )
• common/v1/problems.yaml
• person/v1/name.yaml
• person/v2/name.yaml
• person/identifier/v1beta/identifiers.yaml

Versioning is still on the (sub)domain level, and renaming files or moving types between them are a breaking change.

Private types

If there is a need for private types e.g. substructures in a Problem (sub)type, they could be listed in a privateDefinitions property instead of the definitions one. For OpenAPI 2.0, this still should be OK as long as the JSON Pointer in a $ref points a valid type definition.

[pvdbosch]

In GitLab by @pvdbosch on Dec 12, 2018, 19:56

changed the description

[pvdbosch]

In GitLab by @pvdbosch on Dec 17, 2018, 11:24

assigned to @pvdbosch

[pvdbosch]

In GitLab by @pvdbosch on Dec 17, 2018, 15:46

Decided in the December meeting to repeat the (sub)domain and version in the file name with dash seperator:

• <domain>/<version>/<domain-version>.yaml
• <domain>/<subdomain>/<version>/<domain-subdomain-version>.yaml

Example:

• common/links/v1/common-links-v1.yaml
• common/v1/common-v1.yaml
• problem/v1/problem-v1.yaml

Rationale:

• having folder structure is useful to manage maven builds (i.e. clean subfolder, add to .gitignore), so no flat structure
• having meaningful file name is very useful when opening the files
• each file regrouping types should have its own lifecycle, and thus forms its own (sub)domain.

Other decisions:

• create a separate domain (folder) for problem types (name singular 'problem', not 'problems')
• add swagger metadata block to each YAML file with schemas:
  • it makes them editable with swagger editors
  • it is possible to also extract other Swagger parts as well into them, and reference them from the API definition, e.g. paths, ResponseObject, ...
  • some elements specific to the JSON Schema standard, like the $schema header, cause problems and aren't valid OpenAPI/Swagger elements. Version and other metadata can be added in the swagger block instead. Properties in a swagger file not part of the standard have to start with x-.

When publishing through HTTP, we could expose previous versions of a YAML as well:

problem/v1.1
problem/v1.0
problem/v1   => returns same YAML file as problem/v1.1

[pvdbosch]

In GitLab by @pvdbosch on Dec 21, 2018, 14:41

schemas and styleguide are updated (on git, not published yet) according to decisions reached on this issue

[pvdbosch]

In GitLab by @pvdbosch on Jan 3, 2019, 14:34

also added some parameters to schemas:

• in common-v1.yaml: LangQueryParameter and PageQueryParameter
• in person-identifier-v1beta.yaml: SsinPathParameter

[pvdbosch]

In GitLab by @pvdbosch on Jan 22, 2019, 13:49

mentioned in commit 1359e2e

[pvdbosch]

In GitLab by @pvdbosch on Jan 22, 2019, 14:40

closed

[pvdbosch]

In GitLab by @pvdbosch on May 10, 2019, 09:26

mentioned in commit 9e444af