imperativeStatus and validationModes

[nickevansuk]

Use case

Representing different property imperative configurations across validationModes

Proposal

For a particular subset of validationMode (e.g. C1Request, C2Request) a specific imperativeConfiguration should be applied.

If no matching validationMode is found for the current mode, the default values for the imperativeConfiguration from the model root should be used. This means that validationMode and imperativeConfiguration properties are only required in the model where there is variance in their use between modes, otherwise the default can be used without cluttering the model files.

If a matching validationMode is found for the current mode, then the imperativeConfiguration it references should be used and the values of requiredFields, recommendedFields, shallNotInclude in the model root should be completely ignored

shallNotInclude should be added just within imperativeConfiguration, to represent properties that are not expected to be found in a particular imperativeConfiguration, but are still in the spec.

Example

{
   "type":"Lease",
   "subClassOf": "https://schema.org/Thing",
   "validationMode":{
     "C1Request": "request",
     "C2Request": "request"
   }
   "imperativeConfiguration":{
      "request":{
         "hasId":false,
         "requiredFields":[
            "type",
            "leaseExpires"
         ],
         "recommendedFields":[

         ],
         "shallNotInclude":[

         ],
         "requiredOptions":[

         ]
      }
   },

Implementation requirements

Rules

• New rule to recognise shallNotInclude (called ShallNotIncludeFieldsRule?) and produce error messages as appropriate (note that shallNotInclude does not exist in the default mode, and only exists in imperativeConfiguration)
• Update to the existing RequiredFieldsRule, RequiredOptionalFieldsRule and RecommendedFieldsRule to respect the input validationMode and resolve/use the relevant imperativeConfiguration instead of the default.

Data model tests

• Data model tests to ensure that all fields featured in the imperativeConfiguration within requiredFields, recommendedFields, shallNotInclude, and requiredOptions exist in inSpec within the same model
• Data model tests to ensure that all validationModes specified are valid (valid list is inferred from meta.json see below)
• Data model tests to ensure that all validationModes reference valid imperativeConfigurations within the same model

Making modes accessible

The data model library should include an accessible enumeration of validationModes which are configured in meta.json.

This should be the source of truth for available validationMode values, and can be used to drive the validator GUI.

"validationModeGroup":[
  {
    "name": "Opportunity Data Publishing"
    "validationModeList": [
      {
        "validationMode": "RPDEFeed" // note will just be handled as default everywhere as unrecognised
        "name": "Open Data Listings RPDE Feed"
      },
      {
        "validationMode": "BookableRPDEFeed"
        "name": "Open Data Bookable RPDE Feed"
      }
    ]
  },
  {
    "name": "Open Booking API"
    "validationModeList": [
      {
        "validationMode": "C1Request"
        "name": "C1 Request"
      },
      {
        "validationMode": "C1Response"
        "name": "C1 Response"
      },
      {
        "validationMode": "C2Request"
        "name": "C2 Request"
      }
      ...
    ]
  }
]

Representation in the Validator GUI

The validation group mentioned above can then be represented in the Validator GUI as a button next to the "VALIDATE" button, that uses existing design patterns to allow selection of the validation mode.

The validation mode must also be able to be set in the URL of the validator, such that someone hyperlinking to that a specific sample has the mode preset

Sample grouping

The existing example_list.json needs to be adjusted as below to include grouping capability similar to the above.

[
  {
    "name": "Opportunity Data Publishing"
    "exampleList": [
        {
          "file": "sessionseries_example_1.json",
          "name": "SessionSeries with ScheduledSession Example"
        },
        {
          "file": "scheduledsession_example_1.json",
          "name": "ScheduledSession with SessionSeries Example"
        },
        {
          "file": "sessionseries-split_example_1.json",
          "name": "SessionSeries Example"
        }
    ]
  },
  {
    "name": "Open Booking API"
    "exampleList": [
        {
          "file": "c1_request_example_1.json",
          "name": "C1 Request Example",
          "validationMode": "C1Request"
        },
        {
          "file": "c1_response_example_1.json",
          "name": "C1 Response Example (simple)",
          "validationMode": "C1Response"
        },
        {
          "file": "c1_response_example_2.json",
          "name": "C1 Response Example (with Attendee Details)"
          "validationMode": "C1Response"
        }
    ]
  }

Samples within the Validator GUI

The GUI of the validator then needs to render these groups for the examples.

As the example list is quite long, consider how the list will scale as the number of examples increases.

[henryaddison]

@nickevansuk I have made a start on some of the rules and model specs for this as you can see in the two PRs linked above. Third one to follow soon (work done just need to push it when I can access it again). This probably marks about the end of the initial timebox for working on the model validator library's rules (I might be able to squeeze in moving the source of truth for available validation modes from the validator library to the data-models repo).

[henryaddison]

@nickevansuk I am getting through the work for this issue and so thinking a bit how these changes will be deployed.

Adding validationModeGroup to the metadata in data-models doesn't break anything but the validator site will come to rely on it. My suggestion is therefore to make a new minor version of data-models (1.6.0 from 1.5.6 I think) so the changes to the validator site can specify only later versions.

However, the changes to the examples/samples is more complex as rather than a pure addition it is a change to data-models which is not backwards compatible with the validator site code (before the validator site expects examples to be a flat list of objects, after it is groups of lists). I assume this is not a case of creating a new version of the spec in data models but instead should be a change of version of the @openactive/data-models npm pacakge, which I think strictly should be a new major version (2.0) to indicate the breaking change.

Basically do you agree with me updating the npm package's version to 2.0.0 in #46 ?

[nickevansuk]

yep updating the models to 2.0 is fine, we're doing fairly major tooling work across the board so makes sense to me

[thtg88]

If I understand this correctly does this mean we will also have to bump major in models-lib/package.json?

[henryaddison]

@thtg88 Other than the change to the Barcode.json file name none of the changes I'm making effect the models-lib (yet) and even the file rename doesn't seem to be an issue for the code generator either so you shouldn't HAVE to but it may probably be wise to update the version in models-lib once it's released to avoid failing behind.

[henryaddison]

I have noticed that the Rules in data-model-validator lib are quite highly coupled to a version of the spec in data-models lib due to the way rules are target fields, models and validation modes. This is unavoidable - for new versions of the spec there will need to be some new rules and some old rules will no longer apply. However, the way it is currently implemented means the rules are at risk of accidentally being ignored due to types in the strings used by targetFields, targetModels and targetValidationModes.

At some point I guess it will be necessary to have per-version collections of the rules to apply during validation and therefore more explicitly include version when constructing a new include of a Rule class (maybe this is already possible since constructor takes an OptionsHelper object) and add some validation of the values of targetModels, targetFields and targetValidationModes against the models, fields and validation modes that exist in the data models spec for that version.

[nickevansuk]

Yes great point about having the rules target specific versions - if this isn't there already, presumably the way to do this would be by adding targetVersions to the rules, which for now would all be either 2.0or 2.x (depending on the below)

We had a design discussion originally about versions of the model and decided that we didn't want a set of model files for each minor version, as that would be a nightmare to maintain! Instead we opted for 2.x to represent the "latest" minor version, as any changes made in a minor version by definition need to be non-breaking, and so the model should not become more restrictive over time, only more expansive.

I'm not sure what version ends up being used by the time you get to the rule itself (i.e. this.options.version within the rule), but whichever that is we should probably be consistent with it in terms of the granularity of targetVersions.

So if this.options.version is 2.x then:

• Allow only 2.x, 3.x etc (as defined by the values of the object in versions.js) to be specified in the targetVersions

If this.options.version is 2.0 then:

• Allow either 2.1 or 2.x to be specified in the targetVersions (as defined by the union of keys and values in versions.js), to allow us to be consistent, and have rules applicable to minor versions if required

Could we add "targetVersions support and some validation of the values of targetModels, targetFields and targetValidationModes against the models, fields and validation modes that exist in the data models spec for that version" to the spreadsheet to pick up? Sounds like it will be useful if we're about to embark on extensive rule writing?

[henryaddison]

@nickevansuk & @thill-odi,

With the merging of the changes to the validator site above (openactive/data-model-validator-site#56), I believe that completes the work for this issue (bar possibly our comments about validating validationModes, targetModels and targetFields - this has been added to bottom of spreadsheet and perhaps belongs in it's own issue).

Work is merged into master but I will leave to you to confirm all is good and to deploy the updates to the production site (not least because I don't know how it's hosted!).