Formalize YAML ModSpec approach

[ronaldtse]

In OGC GeoPose, ISO 19115-3 and ISO 19135, we have implemented a Liquid template to convert ModSpect instances from YAML to presentation.

This involves 2 Liquid templates:

• Requirements class + Provision / Requirement / Recommendation / Permission
• Conformance class + Conformance test

We wish to formalize this approach for users (ModSpec users including OGC and ISO/TC 211) to use.

The implementation of this can be found here:

• OGC GeoPose: https://github.com/metanorma/ogc-GeoPose/tree/main/standard/standard/modspec
• ISO 19115-3: https://github.com/metanorma/iso-19115-3/tree/main/sources/ed2/sections/tables
• ISO 19135: https://github.com/metanorma/iso-19135/tree/main/sources/iso-19135-2021/sections/templates

We will also need to update documentation on metanorma.org.

This would greatly assist our current work with the MUDDI SWG.

[opoudjis]

Remains desirable, some editors really like this; but because it hasn't been documented or advertised, not clear if it has had adequate testing or usage to solidify it.

[opoudjis]

This is an interim YAML solution, which we can document, pending the machine readable modspec of #242

"Could write a blog post, and reference that"

[ghobona]

Discussed 2024-02-15

[opoudjis]

@manuelfuenmayor Could you possibly write a blog post documenting the usage of YAML in modspec? If not, I'll do so, but you are more familiar with it than I am, I like to think :)

[opoudjis]

I will investigate whether there are YAML schemas that we can exploit in this formalisation.

[opoudjis]

(Old) solutions are shown on https://json-schema-everywhere.github.io/yaml

https://www.npmjs.com/package/pajv

It's in Node, and it's an extension of the horrific JSON Schema validator ajv.

If this yields unacceptable obscure validation responses, or if we we can always convert the YAML to ruby hashes, and validate them programmatically.

There are Ruby implementations of other validators listed, not based on JSON-Schema: https://rx.codesimply.com/ and https://github.com/kvs/kwalify, but they are unmaintained. (Kwalify last updated in 2009, Rx in 2008!) In fact, even pajv was last updated in 2017: https://github.com/json-schema-everywhere/pajv/ . YAML validation is simply not a current concern to people.

There are more recent Node-based validators, of which some use JSON Schema and some do not:

• https://github.com/ketanSaxena/schema-validator
• https://www.npmjs.com/package/salty-dog
• https://www.npmjs.com/package/v8r
• https://www.npmjs.com/package/grunt-yaml-validator
• https://www.npmjs.com/package/simple-yaml-validator
• https://www.npmjs.com/package/yaml-schema
• https://www.npmjs.com/package/yaml-validator-typescript
• https://www.npmjs.com/package/yval
• https://github.com/ssbarnea/elvy

There are also several Ruby validators more recent than Kwalify: https://rubygems.org/search?query=yaml+validator . OTOH, Kwalify has 28M downloads, and the next generic validator gem is 50K. Kwalify clearly remains popular.

And there are JSON-Schema validators natively in Ruby; they don't consume YAML natively, but a YAML to JSON transformation is trivial.

So we have several options for validation, and the choice depends on

• Whether we want an externally defined formal schema (which really means JSON Schema)
• Whether we want native Ruby support

It looks like the most popular Ruby-native JSON Schema validator, https://github.com/voxpupuli/json-schema/ , would work.

[ghobona]

So it's a choice between https://github.com/voxpupuli/json-schema/ and https://github.com/kvs/kwalify

The fact that kwalify is unmaintained rules it out, in my opinion.

[ronaldtse]

@opoudjis we use JSON/YAML schemas for Glossarist already so we should continue the practice.

[opoudjis]

Right, useful to know. OK, then it will be voxpupuli, when whoever it is defines the JSON Schema for Modspec.

[ronaldtse]

FYI I've made a first cut here, serializable to YAML/JSON/XML schema:

• https://github.com/metanorma/modspec-ruby

[manuelfuenmayor]

FYI I've made a first cut here, serializable to YAML/JSON/XML schema:

Hm, perhaps this affects the validity of the blog post I've written?

[ronaldtse]

Hm, perhaps this affects the validity of the blog post I've written?

The post has been merged. Thanks!

[ronaldtse]

The next to do is to create a Metanorma/LutaML plugin that uses the modspec gem. It already provides the JSON/YAML/XML Schemas.

[ghobona]

Adding the Blog posts's link for future reference.

https://www.metanorma.org/blog/2024-04-04-ogc-modspec-in-yaml/

[ronaldtse]

The integration ticket is:

• https://github.com/metanorma/modspec-ruby/issues/2