3.1.  General

The Metanorma document revision format consists of the following core models:

The revision format follows this hierarchical structure:

+-------------------+
|  RevisionHistory  |
|                   |
| +revisions        |
+--------+----------+
         |
         | 1..*
+--------v----------+      +------------+
|     Revision      |      |  DateInfo  |
|                   |      |            |
| -edition          |<>--->| -type      |
| -relation_type    |      | -value     |
| +date             |      |            |
| +contributor      |      +------------+
| +amend            |
+--------+----------+
         |
    +----+----+---------------------+
    |         |                     |
+---v---+ +---v----------+  +-------v--------+
|Person | | Organization |  | Amendment      |
|       | |              |  |                |
| +name | | -name        |  | -description   |
|       | | -subdivision |  | -change        |
|       | | -abbreviation|  | +location      |
+---+---+ +--------------+  | +classification|
    |                       +-------+--------+
    |                               |
    |                  +------------+------+
+---v---+              |                   |
| Name  |       +------+-------+   +-------+-------+
|       |       |  Location    |   | Classification|
| -abbr |       |              |   |               |
| -full |       | -type        |   | -tag          |
+-------+       | -value       |   | -value        |
                +--------------+   +---------------+

3.2.  RevisionHistory

The RevisionHistory class is the main container for all revisions.

class RevisionHistory
  attribute :revisions, Revision, collection: true
end

3.3.  Revision

The Revision class represents a single revision entry, which may include multiple amendments.

class Revision
  attribute :date, DateInfo, collection: true
  attribute :edition, :string
  attribute :contributor, Contributor, collection: true
  attribute :amend, Amendment, collection: true
  attribute :relation_type, Amendment, collection: true
end

The date attribute is a collection of DateInfo objects that provide information about when the revision occurred.

The edition attribute is a string that represents the version number or identifier for the revision.

The contributor attribute is a collection of Contributor objects representing the people or organizations responsible for the revision.

The amend attribute is a collection of Amendment objects representing the changes made in the revision.

The relation_type attribute is a collection of Amendment objects representing the relationship between this revision and others, if applicable.

3.4.  DateInfo

The DateInfo class represents date information associated with a revision.

class DateInfo
  attribute :type, :string
  attribute :value, :string
end

The type attribute is a string indicating the type of date, such as “published” or “updated”.

The value attribute is a string containing the date value.

3.5.  Contributor

The Contributor class represents a person or organization responsible for a revision.

class Contributor
  attribute :person, Person
  attribute :organization, Organization
end

3.6.  Person

The Person class represents an individual contributor.

class Person
  attribute :name, Name
end

3.7.  Organization

The Organization class represents an organizational contributor.

class Organization
  attribute :name, :string
  attribute :subdivision, :string
  attribute :abbreviation, :string
end

The name attribute is a string containing the organization’s name.

The subdivision attribute is an optional string specifying a department or division within the organization.

The abbreviation attribute is an optional string providing an abbreviated form of the organization’s name.

3.8.  Name

The Name class represents a person’s name.

class Name
  attribute :abbreviation, :string
  attribute :completename, :string
end

The abbreviation attribute is a string containing the person’s initials or abbreviation.

The completename attribute is a string containing the person’s full name.

3.9.  Amendment

The Amendment class represents a specific change or set of changes made to the document.

class Amendment
  attribute :description, :string
  attribute :location, Location, collection: true
  attribute :classification, Classification, collection: true
  attribute :change, :string, default: -> { "modify" }
end

The description attribute is a string describing the changes made.

The location attribute is a collection of Location objects specifying the parts of the document affected by the amendment.

The classification attribute is a collection of Classification objects categorizing the amendment.

The change attribute is a string indicating the type of change, defaulting to “modify”.

3.10.  Location

The Location class specifies the part of the document affected by an amendment.

class Location
  VALID_TYPES = %w[
    section clause part paragraph chapter page line table annex figure
    example note formula list time anchor whole
  ].freeze

  attribute :value, :string
  attribute :type, :string, values: VALID_TYPES
end

The value attribute is a string specifying the specific value of the location, such as “4.0” for clause 4.0, or “B” for Annex B.

The type attribute is a string indicating the type of location, such as “clause”, “annex”, or “whole”.

3.11.  Classification

The Classification class categorizes an amendment according to specific attributes.

class Classification
  attribute :tag, :string
  attribute :value, :string
end

The tag attribute is a string indicating the classification category, such as “severity” or “type”.

The value attribute is a string specifying the classification value, such as “major” or “editorial”.

4.1.  YAML format

The Metanorma document revision format can be serialized as YAML, which is often used in configuration files and is human-readable.

revisions:
  - date:
    - type: published
      value:  2012-04
    edition: 1.0.0
    contributor:
    - person:
        name:
          abbreviation: JMS
          completename: J. Michael Straczynski
    amend:
      - description: Approved edition of S-102
  - date:
    - type: updated
      value:  2017-03
    edition: 2.0.0
    contributor:
    - organization:
        name: S-102PT
    amend:
      - description: |
          Updated clause 4.0 and 12.0.

          Populated clause 9.0.
        location:
          - type: clause
            value: 4.0
          - type: clause
            value: 12.0
          - type: clause
            value: 9.0
          - type: whole
        classification:
          - tag: severity
            value: major
          - tag: type
            value: editorial
      - description: Deleted contents of Annex B in preparation for updated S-100 Part 10C guidance.
        location:
          - type: annex
            value: B

4.2.  XML format

The same revision history can also be serialized as XML, which is commonly used for structured data interchange.

<?xml version="1.0" encoding="UTF-8"?>
<revision-history>
  <revision>
    <date>
      <type>published</type>
      <value>2012-04</value>
    </date>
    <edition>1.0.0</edition>
    <contributor>
      <person>
        <name>
          <abbreviation>JMS</abbreviation>
          <completename>J. Michael Straczynski</completename>
        </name>
      </person>
    </contributor>
    <amend>
      <description>Approved edition of S-102</description>
    </amend>
  </revision>
  <revision>
    <date>
      <type>updated</type>
      <value>2017-03</value>
    </date>
    <edition>2.0.0</edition>
    <contributor>
      <organization>
        <name>S-102PT</name>
      </organization>
    </contributor>
    <amend>
      <description>Updated clause 4.0 and 12.0.

Populated clause 9.0.</description>
      <location type="clause">4.0</location>
      <location type="clause">12.0</location>
      <location type="clause">9.0</location>
      <location type="whole"></location>
      <classification>
        <tag>severity</tag>
        <value>major</value>
      </classification>
      <classification>
        <tag>type</tag>
        <value>editorial</value>
      </classification>
    </amend>
    <amend>
      <description>Deleted contents of Annex B in preparation for updated S-100 Part 10C guidance.</description>
      <location type="annex">B</location>
    </amend>
  </revision>
</revision-history>

5.1.  Parsing revision history

require 'revix'

# Parse from YAML string
yaml_content = File.read('revision_history.yaml')
history = Revix::RevisionHistory.from_yaml(yaml_content)

# Access revision data
history.revisions.each do |revision|
  puts "Edition: #{revision.edition}"

  revision.date.each do |date|
    puts "Date: #{date.value} (#{date.type})"
  end

  revision.contributor.each do |contributor|
    if contributor.person
      puts "Contributor: #{contributor.person.name.completename} (#{contributor.person.name.abbreviation})"
    elsif contributor.organization
      puts "Contributor: #{contributor.organization.name}"
    end
  end

  revision.amend.each do |amendment|
    puts "Amendment: #{amendment.description}"

    amendment.location&.each do |location|
      if location.value
        puts "  Location: #{location.type}=#{location.value}"
      else
        puts "  Location: #{location.type}"
      end
    end

    amendment.classification&.each do |classification|
      puts "  Classification: #{classification.tag} = #{classification.value}"
    end
  end
end

require 'revix'

# Parse from XML string
xml_content = File.read('revision_history.xml')
history = Revix::RevisionHistory.from_xml(xml_content)

# Access revision data (same as with YAML)
# ...

5.2.  Creating revision history

The following Ruby code demonstrates how to create a revision history programmatically:

require 'revix'

# Create a revision history object
history = Revix::RevisionHistory.new(revisions: [
  Revix::Revision.new(
    date: [Revix::DateInfo.new(type: "published", value: "2012-04")],
    edition: "1.0.0",
    contributor: [
      Revix::Contributor.new(
        person: Revix::Person.new(
          name: Revix::Name.new(
            abbreviation: "JMS",
            completename: "J. Michael Straczynski"
          )
        )
      )
    ],
    amend: [
      Revix::Amendment.new(
        description: "Approved edition of S-102",
        location: [
          Revix::Location.new(type: "clause", value: "4.0"),
          Revix::Location.new(type: "whole")
        ]
      )
    ]
  )
])

5.3.  Serializing revision history

# Serialize to YAML
yaml_content = history.to_yaml
File.write('revision_history.yaml', yaml_content)

# Serialize to XML
xml_content = history.to_xml
File.write('revision_history.xml', xml_content)

6.1.  Amendment descriptions

Amendment descriptions should be:

6.2.  Location specificity

Locations should be as specific as possible:

6.3.  Change classification

Classifications help users understand the impact and nature of changes:

6.4.  Date information

Date information should:

6.5.  Multiple contributors

When multiple contributors are involved: