schema form

There's an old branch where Jon and I broke up the schema into separate schemas for each response, see https://github.com/hapi-server/data-specification-schema/tree/jon-jeremy-mess-3.0. In addition, this area contains Jython scripts to convert the separated schemas back into the one schema used in the Verifier, and another which separates the one schema into separate ones.

To close that branch, we need to consider how this will be handled. We have three alternatives:

1. always use the combined
2. always use the separate
3. provide both the separate and combined

Option 1, always use the combined:

pros:

• existing code continues to work without modification
• avoids unnecessary repeats of checks in each schema

cons:

• schemas cannot be used to interactively check HAPI responses in IntelliJ or VSCode or https://www.jsonschemavalidator.net/
• undocumented JSON form used within the Validator exists.

Option 2, always use the separate

pros:

• schemas can be immediately used with JSON responses, and one can interactively check HAPI responses in IntelliJ or VSCode or https://www.jsonschemavalidator.net/
• JSON responses from any server can contain schema reference, asserting base level of syntax is followed.
• smaller JSON schemas are more easily modified since you don't need to scroll past catalog schema to modify info schema.

cons:

• modification of Verifier code is necessary

Option 3, provide both the separate and combined

pros:

• scripts to separate and combine are already written
• Storage cost is trivial, relatively easy to explain why there are two in documentation.

cons:

• always dangerous to have multiple copies of the same information which must be kept in sync.
• need to identify and document procedure for modifying
• Jython combine and separate scripts should be ported to Python.
• We need to be careful to make sure tag order is preserved.

Notes: Bob mentioned OpenAPI is expecting one JSON schema.