Subset mode - use schema version to simplify profile work
jautor opened this issue · 1 comments
jautor commented
In subset
mode, a schema is only included if it is listed in the profile. But once listed, all properties within the schema are included in the output unless individual entries are made in the profile for each property.
For documenting service implementations, it is typically much less work to remove unsupported properties from the list than to list every supported property.
Add three new methods to reduce the amount of profile work required to produce a specific subset of schema:
- Support
MinVersion
in theResourceRequirements
to mean that the specified version is the "highest version supported" by the service - so the output should not include any later versions. This removes the need to manually edit the property lists for schema versions beyond those supported by the implementation. More importantly, it allows the documentation to be updated to later versions of schema with very minimal work in the profile. - Use Resource-level
ReadRequirement
values to indicate the default treatment of properties. The two values allow for a starting point of "all" or "none" to reduce the work required in the profile.
--Supported
indicates all properties should be included (this is the default today when noPropertyRequirements
are present)
--IfPopulated
indicates no properties should be included unless they are specified withinPropertyRequirements
(this is the behavior when any property requirement is specified) - Support property-level deletion using the property-level
ReadRequirement
value of "None". This allows minimal profile work to show a schema that is mostly supported.
akf commented
Clarifications:
- MinVersion here is being used to mean "version supported." Probably we want to add a subset-specific keyword for this. Authors may want "everything from version x.y MINUS some things."
- Goal is to be able to either "start from zero and list properties," or "start from a given version and list properties to remove."