Validation of OGC requirements as standalone YAML

[opoudjis]

metanorma/ogcapi-processes#2 has resulted in the addition of OGC requirements, properly specified, to metanorma-ogc, as documented in https://www.metanorma.org/author/ogc/topics/requirements/

The Modular Specification, https://www.ogc.org/standards/modularspec, has a grammar of OGC requirements, setting out the cardinalities and attributes of different types of requirement; see Appendix C of that document, which is also represented in https://github.com/opengeospatial/NamingAuthority/blob/master/definitions/models/modspec.ttl and in metanorma/metanorma-requirements-models#11 (which resulted in a LutaML encoding of the UML in ModSpec Appendix C).

It is desirable to validate requirements entered for OGC against this model. This validation could be done within metanorma, but it makes more sense to validate OGC requirements as standalone YAML files, to be included into OGC Metanorma documents via a lutaml plugin.

So

[recommendation,label=/ogc/recommendation/wfs/2,obligation=permission,subject=user,inherit=/ss/584/2015/level/1,classification="control-class:Technical;priority:P0"]
.Widgets
====
[.component,class=conditions]
---
. Candidate test subject is a witch
. Widget has been suitably calibrated for aerodynamics
---

[.component,class=part]
---
Determine travel distance by flight path
---

[[a2]]
[.component,class=part]
---
Independently verify flight path
---

Widgets are tested for aerodynamic flight potential in partnership with witches.
Consult local coven for more information.
====

would be sourced as a standalone YAML file looking like:

class: recommendation
type: requirement_class
obligation: permission
label: /ogc/recommendation/wfs/2
subject: user
inherit: /ss/584/2015/level/1
classification:
  control-class: technical
  priority: p0
caption: Widgets
component:
  conditions:
    - Candidate test subject is a witch
    - Widget has been suitably calibrated for aerodynamics
  part:
    - Determine travel distance by flight path
    - Independently verify flight path

text: |
  Widgets are tested for aerodynamic flight potential in partnership with witches.
  Consult local coven for more information.

And the file would be validated by lutaml for conformance to the UML grammar according to its type.

[ghobona]

Discussed with OGC staff on 2023-11-06.

Agreement to leave this Issue open until a resource becomes available to work on it.

The resource would be a ruby developer that understands the ModSpec.

[ghobona]

Discussed 2024-02-15

Ribose will provide a prototype for showing to the OAB.

[ghobona]

@opoudjis to look into whether there is a schema validation tool/language for YAML (e.g. similar to JSON Schema or XSD).

[opoudjis]

Done in #493 (comment) . There are lots of ad hoc schemas specific to implementations, and done as YAML objects themselves. But the standard way of doing it is JSON Schema, since JSON and YAML are both just serialisations of objects; and there is a well-used Ruby implementation of JSON Schema. JSON Schema is kind of clumsy, but I would recommend its use as a recognised standard.

[ronaldtse]

Validation implementation:

• Provide "validate" method modspec-ruby#4

[ronaldtse]

This is done in:

• Add validation methods modspec-ruby#7

[opoudjis]

Review and confirm

[opoudjis]

This ticket did ask for schema validation, but the deserialisation is strongly bound to the schema, so it's not clear there is much point in doing so.

metanorma/mn-requirements#30 will make it possible to swap between validating a Modspec YAML suite, and validating Modspec in the context of a document: both will be validated as a suite of Modspec objects. This ticket will then refactor mn-requirements so that it uses the validation methods ported to modspec-ruby, and so that it does validation of Modspec extracted out of a Metanorma document. It will also do schema validation, if we have a schema worth validating against.