JSON Schema about datahelix HOT 4 CLOSED

• Improving the documentation also (all in one place).
• JSON schema could be used to validate that the profile is valid when its being generated manually.
• Which milestone would this be for?

from datahelix.

Should be completed before or with #383

from datahelix.

Acceptance criteria

• JSON schema file created for V3 version of profile
• Schema file committed to repository
• Documentation created/updated and linked to schema file in repository
  • Documentation for the validator updated to show it does/doesn't use the schema
  • Documentation updated to describe how the schema could be used
• Changes made to the ProfileReader/ProfileValidator (or a new implementation created) to validate the input profile against the schema or a new ticket raised to cover this change and any investigation
• Tests created to prove that the schema is valid, details of this test should be contained in the documentation
  • For users/contributors if they need to do the same in future, e.g. if the profile and/or schema changes or in other products.
• Automated tests written for any changes made to production code (e.g. ProfileReader/ProfileValidator

from datahelix.

Meeting to discuss:

Actions:

1. Does the Jackson library support JSON schemas? - @mrspaceman
2. What license requirements/restrictions/guidance do we have to ensure the product is accepted into FINOS? - @mrspaceman
3. What libraries exist, and what licenses do they have, which schema version do they support? - @mrspaceman
4. What version of the JSON schema are we going to adopt? Draft 7? - @mrspaceman
5. What editors do we want to support, what support do we want profile authors to have in those editors? - @mrspaceman
6. What is the default approach for defining a schema in a JSON file? - @SL-Mark
7. Should we use SchemaStore.org? What is the cost, licensing, does it confuse the matter of it being bundled? - @SL-Mark
8. Should the profile shape be improved before the first version of the JSON schema is released? - @sl-slaing / @SL-Mark / @ColinEberhardt
9. Schedule follow-up meeting @mrspaceman

Outcomes:

• Agreed to focus on a strict profile schema initially, i.e. no non-supported properties are permitted in the profile
• Proposing the permissibility of comments within the profile, as Jackson currently supports
• We have decided that we should endeavour to use the latest draft (7) wherever possible
• Profile validation against the profile schema should provide detail of fault in the profile to aid the author in correct it (i.e. line number, violation against the profile schema)
• Internet connectivity requirements are a concern, so the tool should use a 'bundled' copy of the schema and reject schema urls that do not match any that are bundled.
• ? Profile schema url should use the HTTPS scheme
• ? Profile schema url should point to the codebase in GitHub, rather than another hosting provider
• ? URL for the profile schema version should be treated case-insensitively as it would be via a browser.
• ? schemaVersion property will be removed (superseded by the schema directive, see Q6)
• Schema directive will be mandatory
• ? Profile schema versions should be immutable and new versions created for each change
• ? Profile schema version numbers should adopt SemVer versioning

Impact:

• inclusion of a schema directive is more 'complex' (its a url rather than a number)
• profiles will prevent additional properties from being included
• which version of the profile schema needs to be used? where can this information be found, which versions does the current release support

Changes:

• pre-validation will be required to ensure the profile schema version/url is correct before performing JSON schema validation

from datahelix.