= OGC ModSpec in Ruby

== Purpose

The `modspec` Ruby library allows you to work with OGC ModSpec instances
and export/load them from/to YAML.

OGC ModSpec is a specification for specifying requirements and conformance tests
for standards, described in OGC 08-131r3.

== Features

This library allows you to:

* Create and manipulate ModSpec instances:
** normative statements
** conformance tests
** normative statements classes
** conformance classes
** unified ModSpec suite

* Load and save objects from/to YAML
* Perform validations on ModSpec instances
* Combine ModSpec suites


== Installation

Add this line to your application's Gemfile:

[source,ruby]
----
gem 'modspec'
----

Then execute:

[source,shell]
----
$ bundle install
----

Or install it yourself:

[source,shell]
----
$ gem install modspec
----

== Basics

ModSpec instances all have the following core attributes:

`identifier`:: A unique identifier for the instance, as a URI.

** The pattern for a ModSpec class is `/<type>/<class>`, where
*** `<type>` is the type of the instance (`req` for normative statement, `conf` for conformance test)
*** `<class>` is the name of the class (normative statements class or conformance class)

** The pattern for a normative statement or conformance test is `/<type>/<class>/<name>`, where

*** `<type>` is the type of the instance (`req` for normative statement, `conf` for conformance test)
*** `<class>` is the name of the class (normative statements class or conformance class)
*** `<name>` is the name of the instance

`name`::
A human-readable name for the instance

`description`::
A description of the instance

`guidance`::
Guidance on how to implement the instance



== Usage

=== Normative statements class

A normative statements class groups related normative statements.

A normative statements class has the following attributes in addition to the core attributes:

`subject`::
The subject of the normative statements class

`dependencies`::
URI(s) of normative statement classes that this class depends on

`normative_statements`::
A list of normative statements that belong to this class

`belongs_to`::
The normative statements class that this class belongs to

`reference`::
A reference to an external document or resource

`source`::
The source of the normative statements class


.Working with normative statements classes
[example]
====
[source,ruby]
----
normative_statements_class = Modspec::NormativeStatementsClass.new(
  identifier: "/req/example",
  name: "Requirements class",
  dependencies: ["/req/baf"],
  normative_statements: [normative_statement]
)
----

[source,ruby]
----
normative_statements_class.to_yaml
----

[source,yaml]
----
identifier: "/req/example"
name: "Requirements class"
dependencies:
- "/req/baf"
normative_statements:
- identifier: "/req/example/foo"
  name: "Example requirement"
  statement: "This is an example requirement."
  dependencies:
  - "/req/bar"
  - "/req/baz/2"
----

[source,ruby]
----
> yaml = IO.read('example.yaml')
> normative_statements_class = Modspec::NormativeStatementsClass.from_yaml(yaml)
> <#Modspec::NormativeStatementsClass:0x00007f8b1b8b3d08 @identifier="/req/example", @name="Requirements class", @dependencies=["/req/baf"], @normative_statements=[<#Modspec::NormativeStatement:0x00007f8b1b8b3d08 @identifier="/req/example/foo", @name="Example requirement", @statement="This is an example requirement.", @dependencies=["/req/bar", "/req/baz/2"]>]>
> normative_statements_class.name
> "Requirements class"
----
====

Validations:

* *Identifier prefix*: All normative statements within a normative statements
class must share the same identifier prefix as the class itself, followed by a
slash and then the statement's own identifier.


=== Normative statement

A normative statement represents a single requirement in the specification.

A normative statement has the following attributes in addition to the core attributes:

`subject`::
The subject of the normative statement

`obligation`::
The obligation level of the class, one of `requirement`, `recommendation`, `permission`. Defaults to `requirement`.

`statement`::
The text of the normative statement

`condition`::
Conditions that must be met for the statement to apply

`inherit`::
URI(s) of normative statement(s) that this statement inherits from

`indirect_dependency`::
URI(s) of normative statement(s) that this statement indirectly depends on

`implements`::
The higher-level normative statement that this statement implements

`dependencies`::
A list of identifiers for other normative statements that this statement depends on.

`belongs_to`::
The normative statements class that this statement belongs to.

`reference`::
A reference to an external document or resource

`parts`::
A list of normative statements classes that this class is composed


.Working with normative statements
[example]
====
[source,ruby]
----
normative_statement = Modspec::NormativeStatement.new(
  identifier: "/req/example/foo",
  name: "Example requirement",
  statement: "This is an example requirement statement.",
  obligation: "requirement", # default
  parts: [
    "This is a part of the requirement.",
    "This is another part of the requirement."
  ]
  dependencies: ["/req/bar", "/req/baz/2"]
)
----

[source,ruby]
----
normative_statement.to_yaml
----

Will give out:

[source,yaml]
----
identifier: /req/example/foo
name: Example requirement
statement: This is an example requirement statement.
dependencies:
- /req/bar
- /req/baz/2
----

And to load a normative statement from a YAML file:

[source,ruby]
----
> yaml = IO.read('example-foo.yaml')
> normative_statement = Modspec::NormativeStatement.from_yaml(yaml)
> <#Modspec::NormativeStatement:0x00007f8b1b8b3d08 @identifier="/req/example/foo", @name="Example requirement", @statement="This is an example requirement statement.", @dependencies=["/req/bar", "/req/baz/2"]>
> normative_statement.name
> "Example requirement"
----
====


Validations:

* *Unique identifier*: Each normative statement must have a unique identifier
within its parent normative statements class.

* *Valid dependencies*: The dependencies listed for a normative statement must
refer to valid identifiers of other normative statements.


=== Conformance class

A conformance class groups related conformance tests.

A conformance class has the following attributes in addition to the core attributes:

`tests`::
A set of conformance tests that belong to this class

`classification`::
A classification of the conformance class

`dependencies`::
A list of identifiers for other conformance classes that this class depends on

`target`::
A list of identifiers of normative statement(s) that this class targets

`belongs_to`::
A conformance class that this class belongs to

`reference`::
A reference to an external document or resource


.Working with conformance classes
[example]
====
[source,ruby]
----
conformance_class = Modspec::ConformanceClass.new(
  identifier: "/conf/example",
  name: "Conformance class",
  tests: [conformance_test]
)
conformance_class.to_yaml
----

[source,yaml]
----
identifier: "/conf/example"
name: "Conformance class"
tests:
- identifier: "/conf/example/foo"
  name: "Example test"
  description: "This is an example conformance test."
  targets:
  - "/req/example/foo"
----

[source,ruby]
----
> yaml = IO.read('example.yaml')
> conformance_class = Modspec::ConformanceClass.from_yaml(yaml)
> <#Modspec::ConformanceClass:0x00007f8b1b8b3d08 @identifier="/conf/example", @name="Conformance class", @tests=[<#Modspec::ConformanceTest:0x00007f8b1b8b3d08 @identifier="/conf/example/foo", @name="Example test", @description="This is an example conformance test.", @targets=["/req/example/foo"]>], @abstract=false>
> conformance_class.name
> "Conformance class"
----
====


Validations:

* *Identifier prefix*: All conformance tests within a conformance class must
share the same identifier prefix as the class itself, followed by a slash and
then the test's own identifier.

* *Valid targets*: The targets listed for a conformance test must refer to valid
identifiers of existing normative statements.



=== Conformance test

A conformance test verifies compliance with one or more normative statements.

A conformance test has the following attributes in addition to the core attributes:

`targets`::
A list of identifiers for normative statements that this test targets

`belongs_to`::
The conformance class that this test belongs to

`guidance`::
Guidance on how to perform the test

`purpose`::
The purpose of the test

`method`::
The method used to perform the test

`type`::
The type of the test

`reference`::
A reference to an external document or resource

`abstract`::
A boolean indicating whether this test is abstract



.Working with conformance tests
[example]
====
[source,ruby]
----
conformance_test = Modspec::ConformanceTest.new(
  identifier: "/conf/example/foo",
  name: "Example test",
  description: "This is an example conformance test.",
  targets: ["/req/example/foo"],
  test_method: "manual",
  abstract: false
)
conformance_test.to_yaml
----

[source,yaml]
----
identifier: "/conf/example/foo"
name: "Example test"
description: "This is an example conformance test."
abstract: false
test_method: "manual"
targets:
- "/req/example/foo"
----

[source,ruby]
----
> yaml = IO.read('example.yaml')
> conformance_test = Modspec::ConformanceTest.from_yaml(yaml)
> <#Modspec::ConformanceTest:0x00007f8b1b8b3d08 @identifier="/conf/example/foo", @name="Example test", @description="This is an example conformance test.", @targets=["/req/example/foo"], @test_method="manual", @abstract=false>
> conformance_test.name
> "Example test"
----
====


Validations:

* *Valid targets*: The targets listed for a conformance test must refer to valid
identifiers of existing normative statements.


=== Suite

A suite represents the entire specification, including all normative statements
and conformance tests.

NOTE: This is not defined in the ModSpec specification.

.Working with suites
[example]
====
[source,ruby]
----
suite = Modspec::Suite.new(
  identifier: "example-suite",
  name: "Example suite",
  normative_statements_classes: [normative_statements_class],
  conformance_classes: [conformance_class]
)
suite.to_yaml
----

[source,yaml]
----
identifier: "example-suite"
name: "Example suite"
normative_statements_classes:
  - identifier: "/req/example"
    name: "Requirements class"
    normative_statements:
      - identifier: "/req/example/foo"
        name: "Example requirement"
        statement: "This is an example requirement statement."
        dependencies:
          - "/req/bar"
          - "/req/baz/2"
conformance_classes:
  - identifier: "/conf/example"
    name: "Conformance class"
    tests:
      - identifier: "/conf/example/foo"
        name: "Example test"
        description: "This is an example conformance test."
        targets:
          - "/req/example/foo"
----

[source,ruby]
----
> yaml = IO.read('example-suite.yaml')
> suite = Modspec::Suite.from_yaml(yaml)
> <#Modspec::Suite:0x00007f8b1b8b3d08 @identifier="example-suite", @name="Example suite", @normative_statements_classes=[<#Modspec::NormativeStatementsClass:0x00007f8b1b8b3d08 @identifier="/req/example", @name="Requirements class", @dependencies=["/req/baf"], @normative_statements=[<#Modspec::NormativeStatement:0x00007f8b1b8b3d08 @identifier="/req/example/foo", @name="Example requirement", @statement="This is an example requirement statement.", @dependencies=["/req/bar", "/req/baz/2"]>]>], @conformance_classes=[<#Modspec::ConformanceClass:0x00007f8b1b8b3d08 @identifier="/conf/example", @name="Conformance class", @tests=[<#Modspec::ConformanceTest:0x00007f8b1b8b3d08 @identifier="/conf/example/foo", @name="Example test", @description="This is an example conformance test.", @targets=["/req/example/foo"]>], @abstract=false>]>
> suite.normative_statements_classes.first.name
> "Requirements class"
----
====

Validations:

* *No cyclic dependencies*: The suite ensures that there are no circular
dependencies among normative statements.

* *Label uniqueness*: Labels must be unique across all classes within the suite.

* *Dependency validation*: The suite verifies that all dependencies between
normative statements and conformance tests are valid and refer to existing
elements.


The Suite class provides a `from_yaml_files` method to load a Suite instance
from multiple YAML files. This is particularly useful when your specification is
split across several files for better organization and maintainability.

To load a Suite from multiple YAML files:

[source,ruby]
----
require 'modspec'

# Specify the paths to your YAML files
yaml_files = [
  'path/to/normative_statements.yaml',
  'path/to/conformance_tests.yaml'
]

# Create a Suite instance from the YAML files
suite = Modspec::Suite.from_yaml_files(yaml_files)

# Now you can work with the suite object
puts suite.name
puts suite.normative_statements_classes.count
puts suite.conformance_classes.count
----


The `Suite` class provides a `combine` method to merge two suites:

[source,ruby]
----
combined_suite = suite1.combine(suite2)
----

This method merges the two suites into a single suite, ensuring that the
resulting suite is consistent and free of conflicts.


=== Validation process

Validations are typically performed when:

. Creating or modifying individual elements (normative statements, conformance tests, etc.)
. Adding elements to their respective classes
. Combining suites
. Loading a suite from YAML or other formats

If any validation fails, an error or a collection of errors is returned,
describing the specific validation issues encountered.

To manually trigger validation on a suite:

[source,ruby]
----
errors = suite.validate_all
if errors.any?
  puts "Validation errors:"
  errors.each { |error| puts "- #{error}" }
else
  puts "Suite is valid."
end
----

These validation mechanisms help ensure that the created ModSpec instances are
consistent, well-formed, and adhere to the expected structure and relationships.


== Copyright

This gem is developed, maintained and funded by
https://www.ribose.com[Ribose Inc.]

== License

The gem is available as open source under the terms of the
https://opensource.org/licenses/BSD-2-Clause[2-Clause BSD License].