From 027dd1deef6207beb67a4fc1893ba3fa3c982686 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 28 Aug 2024 16:05:25 +0100
Subject: [PATCH 01/18] Add specmark doc

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 README.md   |   3 +-
 specmark.md | 235 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 237 insertions(+), 1 deletion(-)
 create mode 100644 specmark.md

diff --git a/README.md b/README.md
index 85038f0d4..30b01c57b 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,8 @@ standard.
 
 ## Branches and Formats
 
-The editable files are written in a constrained subset of Markdown and are
+The editable files are written in a
+[constrained subset of Markdown](./specmark.md) and are
 stored in the `main` branch.
 
 These files are automatically processed by
diff --git a/specmark.md b/specmark.md
new file mode 100644
index 000000000..5b57ac282
--- /dev/null
+++ b/specmark.md
@@ -0,0 +1,235 @@
+# Markdown for SPDX 3 model specification
+
+The SPDX 3 model is written in a constrained subset of a Markdown flavour
+([Python-Markdown](https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown)
+which is used by [MkDocs](https://www.mkdocs.org/) site generator).
+
+Specific headings and formatting are used to provide information for the
+generation of a machine-readable specification, by the
+[spec-parser](https://github.com/spdx/spec-parser/).
+
+Organisation:
+
+- All the model files are inside the `model/` directory.
+- Profiles are organized in subdirectories (`Core/`, `Dataset/`, etc.)
+- Entities are organised by type in subdirectories (`Classes/`, `Datatypes/`,
+  `Individuals/`, `Properties/`, and `Vocabularies/`).
+- Each entity (class, datatype, individual, property, and vocabulary)
+  is defined in a distinct file.
+
+Content structure:
+
+- Each file starts with a SPDX license information:
+  `SPDX-License-Identifier: Community-Spec-1.0`
+  and follows by one blank line.
+- The content immediately after the license information must begin with an
+  H1 heading containing the entity's name.
+- Each entity type has a predefined set of allowed H2 headings and
+  labeled lists that must be used to structure its content.
+- There must be a blank line before and after a heading.
+- There must be a blank line before the beginning of a list.
+- There must be a blank line after the end of a list.
+
+## Classes
+
+Allowed headings:
+
+- Summary
+- Description
+- Metadata
+  - name: \<class_name\>
+  - SubclassOf: \<class_name\> OR "none" *(Must have one if Instantiability is "Concrete")*
+  - Instantiability: "Abstract" OR "Concrete" *(Default: Concrete)*
+- Properties *(Optional)*
+  - \<property_name\>
+    - type: \<datatype_name\>
+    - minCount: \<number\> *(Optional)*
+    - maxCount: \<number\> *(Optional)*
+  - ...
+- External properties restrictions *(Optional)*
+  - \<external_property_name\>
+    - minCount: \<number\> *(Optional)*
+    - maxCount: \<number\> *(Optional)*
+  - ...
+
+### Class example
+
+```markdown
+SPDX-License-Identifier: Community-Spec-1.0
+
+# Bot
+
+## Summary
+
+An automated agent.
+
+## Description
+
+A class example.
+
+## Metadata
+
+- name: Bot
+- SubclassOf: Agent
+- Instantiability: Concrete
+
+## Properties
+
+- prohibitedTask
+  - type: xsd:string
+  - minCount: 1
+
+## External properties restrictions
+
+- /Core/Element/name
+  - minCount: 1
+```
+
+## Datatypes
+
+Allowed headings:
+
+- Summary
+- Description
+- Metadata
+  - name: \<datatype_name\>
+  - SubclassOf: \<class_name\>
+- Format
+  - pattern: \<regular_expression\>
+
+### Datatype example
+
+```markdown
+SPDX-License-Identifier: Community-Spec-1.0
+
+# DateTime
+
+## Summary
+
+A string representing a specific date and time.
+
+## Description
+
+A DateTime is a string representation of a specific date and time.
+
+## Metadata
+
+- name: DateTime
+- SubclassOf: xsd:dateTimeStamp
+
+## Format
+
+- pattern: ^\d\d\d\d-\d\d-\d\dT\d\d:\d\d:\d\dZ$
+```
+
+## Individuals
+
+Allowed headings:
+
+- Summary
+- Description
+- Metadata
+  - name: \<individual_name\>
+  - type:  \<class_name\>
+- Property Values
+  - \<property_name\>: \<property_value\>
+  - ...
+
+### Individual example
+
+```markdown
+SPDX-License-Identifier: Community-Spec-1.0
+
+# NoneElement
+
+## Summary
+
+An Individual Value example.
+
+## Description
+
+Blah.
+
+## Metadata
+
+- name: NoneElement
+- type: Element
+
+## Property Values
+
+- name: "NONE"
+```
+
+## Properties
+
+Allowed headings:
+
+- Summary
+- Description
+- Metadata
+  - name: \<property_name\>
+  - Nature: "DataProperty" OR "ObjectProperty"
+  - Range: \<datatype_name\> OR \<class_name\>
+
+### Property example
+
+```markdown
+SPDX-License-Identifier: Community-Spec-1.0
+
+# sensor
+
+## Summary
+
+Describes a sensor used for collecting the data.
+
+## Description
+
+Describes a sensor that was used for collecting the data
+and its calibration value as a key-value pair.
+
+## Metadata
+
+- name: sensor
+- Nature: ObjectProperty
+- Range: /Core/DictionaryEntry
+```
+
+## Vocabularies
+
+Allowed headings:
+
+- Summary
+- Description
+- Metadata
+  - name
+- Entries
+  - \<entry_name\>: \<entry_description\>
+  - ...
+
+Each entry in Entries must be written in a single line.
+
+### Vocabulary example
+
+```markdown
+SPDX-License-Identifier: Community-Spec-1.0
+
+# RpsType
+
+## Summary
+
+Specifies the hand shapes used in Rock-Paper-Scissors.
+
+## Description
+
+RpsType specifies the type of a hand shape.
+
+## Metadata
+
+- name: RpsType
+
+## Entries
+
+- paper: A flat, open hand.
+- rock: A closed fist.
+- scissors: Two fingers extended, forming a V shape.
+```

From b01fb1e6381972c497cae6ce23cfcfee5ce33d10 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 28 Aug 2024 16:15:42 +0100
Subject: [PATCH 02/18] Update specmark.md

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/specmark.md b/specmark.md
index 5b57ac282..fd441347e 100644
--- a/specmark.md
+++ b/specmark.md
@@ -19,7 +19,7 @@ Organisation:
 
 Content structure:
 
-- Each file starts with a SPDX license information:
+- Each file must start with SPDX license information:
   `SPDX-License-Identifier: Community-Spec-1.0`
   and follows by one blank line.
 - The content immediately after the license information must begin with an

From 1a8649a7a6e6691c684999cb32021de65fceba8d Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 4 Sep 2024 19:51:35 +0100
Subject: [PATCH 03/18] Add example + add license info as Markdown metadata

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 155 ++++++++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 133 insertions(+), 22 deletions(-)

diff --git a/specmark.md b/specmark.md
index fd441347e..859f968c3 100644
--- a/specmark.md
+++ b/specmark.md
@@ -1,36 +1,147 @@
+---
+SPDX-License-Identifier: Community-Spec-1.0
+---
+
 # Markdown for SPDX 3 model specification
 
 The SPDX 3 model is written in a constrained subset of a Markdown flavour
 ([Python-Markdown](https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown)
 which is used by [MkDocs](https://www.mkdocs.org/) site generator).
 
+Each model element (class, datatype, individual, property, and vocabulary)
+is defined in a distinct file.
+
 Specific headings and formatting are used to provide information for the
-generation of a machine-readable specification, by the
-[spec-parser](https://github.com/spdx/spec-parser/).
+generation of a machine-readable specification, in
+[Resource Description Framework (RDF)](https://en.wikipedia.org/wiki/Resource_Description_Framework)
+data model, by the [spec-parser](https://github.com/spdx/spec-parser/).
 
-Organisation:
+For instance, a summary listed under the "Summary" heading will be represented
+as an `rdfs:comment` in the RDF file. Likewise, a value specified for the
+minCount of a property name under the "Properties" heading will be translated
+into a `sh:minCount` in the RDF file. See an [example](#example).
 
-- All the model files are inside the `model/` directory.
-- Profiles are organized in subdirectories (`Core/`, `Dataset/`, etc.)
-- Entities are organised by type in subdirectories (`Classes/`, `Datatypes/`,
-  `Individuals/`, `Properties/`, and `Vocabularies/`).
-- Each entity (class, datatype, individual, property, and vocabulary)
-  is defined in a distinct file.
+Descriptions provided under the "Description" heading are intended for human
+reference and will not be incorporated into the RDF file.
+
+## Model file content structure
 
-Content structure:
+Each model file must adhere to a strict content structure:
 
 - Each file must start with SPDX license information:
   `SPDX-License-Identifier: Community-Spec-1.0`
   and follows by one blank line.
 - The content immediately after the license information must begin with an
-  H1 heading containing the entity's name.
-- Each entity type has a predefined set of allowed H2 headings and
+  H1 heading containing the element's name.
+- Each element type has a predefined set of [allowed H2 headings](#syntax) and
   labeled lists that must be used to structure its content.
 - There must be a blank line before and after a heading.
 - There must be a blank line before the beginning of a list.
 - There must be a blank line after the end of a list.
 
-## Classes
+## Model file organisation
+
+Apart from the content in each individual file, the file itself has to be
+placed in a specific location, as the spec-parser implies some model semantic
+from the location of the file:
+
+- Each element (class, datatype, individual, property, and vocabulary)
+  is defined in a distinct file.
+- Model file names are case-sensitive and must be identical to the element they
+  represent.
+- All model files must be located within the `model/` directory.
+- Profiles should be organised into subdirectories (e.g., `Core/`, `Dataset/`).
+- Elements should be categorised by their type in subdirectories (e.g.,
+  `Classes/`, `Datatypes/`, `Individuals/`, `Properties/`, `Vocabularies/`).
+
+File and directory organisation:
+
+```text
+.
+├── model
+│   ├── AI
+:   :
+│   ├── Core
+│   │   ├── Classes
+│   │   │   ├── Agent.md
+:   :   :   :
+│   │   │   └── Tool.md
+│   │   ├── Datatypes
+:   :   :   :
+│   │   │   └── SemVer.md
+│   │   ├── Individuals
+:   :   :   :
+│   │   │   └── NoneElement.md
+│   │   ├── Properties
+:   :   :   :
+│   │   │   └── verifiedUsing.md
+│   │   └── Vocabularies
+:   :       :
+│   │       └── SupportType.md
+│   ├── Dataset
+:   :
+```
+
+The living repository at
+<https://github.com/spdx/spdx-3-model/tree/main/model>
+is the best reference.
+
+## Example
+
+This example is taken from the actual file for
+[SimpleLicensingText](https://github.com/spdx/spdx-3-model/blob/main/model/SimpleLicensing/Classes/SimpleLicensingText.md?plain=1)
+class.
+Its name and location in the repository is
+`model/SimpleLicensing/Classes/SimpleLicensingText.md`.
+
+```markdown
+SPDX-License-Identifier: Community-Spec-1.0
+
+# SimpleLicensingText
+
+## Summary
+
+A license or addition that is not listed on the SPDX License List.
+
+## Description
+
+A SimpleLicensingText represents a License or Addition that is not listed on
+the [SPDX License List](https://spdx.org/licenses),
+and is therefore defined by an SPDX data creator.
+
+## Metadata
+
+- name: SimpleLicensingText
+- SubclassOf: /Core/Element
+- Instantiability: Concrete
+
+## Properties
+
+- licenseText
+  - type: xsd:string
+  - minCount: 1
+  - maxCount: 1
+```
+
+will give this RDF graph
+(in [Turtle syntax](https://en.wikipedia.org/wiki/Turtle_(syntax))):
+
+```ttl
+<https://spdx.org/rdf/3.0.1/terms/SimpleLicensing/SimpleLicensingText> a owl:Class,
+        sh:NodeShape ;
+    rdfs:comment "A license or addition that is not listed on the SPDX License List."@en ;
+    rdfs:subClassOf <https://spdx.org/rdf/3.0.1/terms/Core/Element> ;
+    sh:nodeKind sh:IRI ;
+    sh:property [ sh:datatype xsd:string ;
+            sh:maxCount 1 ;
+            sh:minCount 1 ;
+            sh:nodeKind sh:Literal ;
+            sh:path <https://spdx.org/rdf/3.0.1/terms/SimpleLicensing/licenseText> ] .
+```
+
+## Syntax
+
+### Classes
 
 Allowed headings:
 
@@ -52,7 +163,7 @@ Allowed headings:
     - maxCount: \<number\> *(Optional)*
   - ...
 
-### Class example
+#### Class example
 
 ```markdown
 SPDX-License-Identifier: Community-Spec-1.0
@@ -85,7 +196,7 @@ A class example.
   - minCount: 1
 ```
 
-## Datatypes
+### Datatypes
 
 Allowed headings:
 
@@ -97,7 +208,7 @@ Allowed headings:
 - Format
   - pattern: \<regular_expression\>
 
-### Datatype example
+#### Datatype example
 
 ```markdown
 SPDX-License-Identifier: Community-Spec-1.0
@@ -122,7 +233,7 @@ A DateTime is a string representation of a specific date and time.
 - pattern: ^\d\d\d\d-\d\d-\d\dT\d\d:\d\d:\d\dZ$
 ```
 
-## Individuals
+### Individuals
 
 Allowed headings:
 
@@ -135,7 +246,7 @@ Allowed headings:
   - \<property_name\>: \<property_value\>
   - ...
 
-### Individual example
+#### Individual example
 
 ```markdown
 SPDX-License-Identifier: Community-Spec-1.0
@@ -160,7 +271,7 @@ Blah.
 - name: "NONE"
 ```
 
-## Properties
+### Properties
 
 Allowed headings:
 
@@ -171,7 +282,7 @@ Allowed headings:
   - Nature: "DataProperty" OR "ObjectProperty"
   - Range: \<datatype_name\> OR \<class_name\>
 
-### Property example
+#### Property example
 
 ```markdown
 SPDX-License-Identifier: Community-Spec-1.0
@@ -194,7 +305,7 @@ and its calibration value as a key-value pair.
 - Range: /Core/DictionaryEntry
 ```
 
-## Vocabularies
+### Vocabularies
 
 Allowed headings:
 
@@ -208,7 +319,7 @@ Allowed headings:
 
 Each entry in Entries must be written in a single line.
 
-### Vocabulary example
+#### Vocabulary example
 
 ```markdown
 SPDX-License-Identifier: Community-Spec-1.0

From e40a51e048674a41ff17fd3019238b332cdb58d5 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 4 Sep 2024 20:11:37 +0100
Subject: [PATCH 04/18] Add notes on Markdown flavour

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 14 +++++++++++---
 1 file changed, 11 insertions(+), 3 deletions(-)

diff --git a/specmark.md b/specmark.md
index 859f968c3..f7ba4e585 100644
--- a/specmark.md
+++ b/specmark.md
@@ -4,9 +4,8 @@ SPDX-License-Identifier: Community-Spec-1.0
 
 # Markdown for SPDX 3 model specification
 
-The SPDX 3 model is written in a constrained subset of a Markdown flavour
-([Python-Markdown](https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown)
-which is used by [MkDocs](https://www.mkdocs.org/) site generator).
+The SPDX 3 model is written in a constrained subset of a Markdown markup
+language*, with predefined headings.
 
 Each model element (class, datatype, individual, property, and vocabulary)
 is defined in a distinct file.
@@ -24,6 +23,12 @@ into a `sh:minCount` in the RDF file. See an [example](#example).
 Descriptions provided under the "Description" heading are intended for human
 reference and will not be incorporated into the RDF file.
 
+*The Markdown flavour used for the specification is
+[Python-Markdown](https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown)
+as it is used by [MkDocs](https://www.mkdocs.org/) site generator.
+It differs slightly from
+[GitHub Flavored Markdown Spec](https://github.github.com/gfm/).
+
 ## Model file content structure
 
 Each model file must adhere to a strict content structure:
@@ -38,6 +43,9 @@ Each model file must adhere to a strict content structure:
 - There must be a blank line before and after a heading.
 - There must be a blank line before the beginning of a list.
 - There must be a blank line after the end of a list.
+- Any block level elements nested in a list, including paragraphs, sub-lists,
+  blockquotes, code blocks, etc., must always be indented by at least 4
+  spaces for each level of nesting.
 
 ## Model file organisation
 

From 6f41c90e881fc165d83bc187796a983835e3f3e1 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Sat, 7 Sep 2024 16:09:39 +0100
Subject: [PATCH 05/18] Add UTF-8 encoding info

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/specmark.md b/specmark.md
index f7ba4e585..e52be4d6d 100644
--- a/specmark.md
+++ b/specmark.md
@@ -33,6 +33,7 @@ It differs slightly from
 
 Each model file must adhere to a strict content structure:
 
+- All files must be encoded in UTF-8.
 - Each file must start with SPDX license information:
   `SPDX-License-Identifier: Community-Spec-1.0`
   and follows by one blank line.

From 34158a4a20eb4e0d715147bcb8c420c3d625eec4 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Sat, 7 Sep 2024 16:18:07 +0100
Subject: [PATCH 06/18] Link label: example -> an example

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/specmark.md b/specmark.md
index e52be4d6d..7dc96ca67 100644
--- a/specmark.md
+++ b/specmark.md
@@ -17,8 +17,8 @@ data model, by the [spec-parser](https://github.com/spdx/spec-parser/).
 
 For instance, a summary listed under the "Summary" heading will be represented
 as an `rdfs:comment` in the RDF file. Likewise, a value specified for the
-minCount of a property name under the "Properties" heading will be translated
-into a `sh:minCount` in the RDF file. See an [example](#example).
+"minCount" of a property name under the "Properties" heading will be
+translated into a `sh:minCount` in the RDF file. See [an example](#example).
 
 Descriptions provided under the "Description" heading are intended for human
 reference and will not be incorporated into the RDF file.
@@ -68,11 +68,9 @@ File and directory organisation:
 ```text
 .
 ├── model
-│   ├── AI
 :   :
 │   ├── Core
 │   │   ├── Classes
-│   │   │   ├── Agent.md
 :   :   :   :
 │   │   │   └── Tool.md
 │   │   ├── Datatypes

From 8df68c23030bd3e7e59610e4f7ea9462afa40ae3 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Sun, 8 Sep 2024 00:56:36 +0100
Subject: [PATCH 07/18] Add IRI to Medata of Individuals

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 1 +
 1 file changed, 1 insertion(+)

diff --git a/specmark.md b/specmark.md
index 7dc96ca67..6f7c9abcc 100644
--- a/specmark.md
+++ b/specmark.md
@@ -249,6 +249,7 @@ Allowed headings:
 - Metadata
   - name: \<individual_name\>
   - type:  \<class_name\>
+  - IRI: \<IRI\>
 - Property Values
   - \<property_name\>: \<property_value\>
   - ...

From 27c0ebce9eedd34dd4907abe3a1854cf7803ac0d Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Sun, 8 Sep 2024 01:31:16 +0100
Subject: [PATCH 08/18] Add explanation why blank lines are needed

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/specmark.md b/specmark.md
index 6f7c9abcc..70be13b3a 100644
--- a/specmark.md
+++ b/specmark.md
@@ -23,6 +23,9 @@ translated into a `sh:minCount` in the RDF file. See [an example](#example).
 Descriptions provided under the "Description" heading are intended for human
 reference and will not be incorporated into the RDF file.
 
+The same Markdown files are used to generate the HTML files for
+[the website](https://spdx.github.io/spdx-spec/).
+
 *The Markdown flavour used for the specification is
 [Python-Markdown](https://www.mkdocs.org/user-guide/writing-your-docs/#writing-with-markdown)
 as it is used by [MkDocs](https://www.mkdocs.org/) site generator.
@@ -48,6 +51,10 @@ Each model file must adhere to a strict content structure:
   blockquotes, code blocks, etc., must always be indented by at least 4
   spaces for each level of nesting.
 
+The last four points are because of
+MkDocs' [strict processing](https://python-markdown.github.io/#differences)
+of Markdown files.
+
 ## Model file organisation
 
 Apart from the content in each individual file, the file itself has to be

From 81e99625524c425ac7c0f4de733a1d15c2270d13 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Sat, 19 Oct 2024 05:00:24 +0800
Subject: [PATCH 09/18] Update Individual example

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/specmark.md b/specmark.md
index 70be13b3a..4d038efaf 100644
--- a/specmark.md
+++ b/specmark.md
@@ -255,7 +255,7 @@ Allowed headings:
 - Description
 - Metadata
   - name: \<individual_name\>
-  - type:  \<class_name\>
+  - type: \<class_name\>
   - IRI: \<IRI\>
 - Property Values
   - \<property_name\>: \<property_value\>
@@ -270,11 +270,11 @@ SPDX-License-Identifier: Community-Spec-1.0
 
 ## Summary
 
-An Individual Value example.
+A named individual example.
 
 ## Description
 
-Blah.
+A named individual of Element class that representing none.
 
 ## Metadata
 

From e06f896bad4243ba416a0b78eb6313ac9661ad05 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Mon, 4 Nov 2024 15:43:59 +0000
Subject: [PATCH 10/18] Add notes on bare links and RFCs

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 100 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)

diff --git a/specmark.md b/specmark.md
index 4d038efaf..6a30382f9 100644
--- a/specmark.md
+++ b/specmark.md
@@ -1,4 +1,5 @@
 ---
+SPDX-FileCopyrightText: 2024 SPDX Project
 SPDX-License-Identifier: Community-Spec-1.0
 ---
 
@@ -7,6 +8,24 @@ SPDX-License-Identifier: Community-Spec-1.0
 The SPDX 3 model is written in a constrained subset of a Markdown markup
 language*, with predefined headings.
 
+This document provides guidelines for writing model files in the specific syntax used by SPDX 3.
+
+## Table of contents
+
+- [Overview](#overview)
+- [Model file content structure](#model-file-content-structure)
+- [Model file organisation](#model-file-organisation)
+- [Syntax](#syntax)
+  - [Classes](#classes)
+  - [Datatypes](#datatypes)
+  - [Individuals](#individuals)
+  - [Properties](#properties)
+  - [Vocabularies](#vocabularies)
+- [Example](#example)
+- [Writing style for consistent documentation](#writing-style-for-consistent-documentation)
+
+## Overview
+
 Each model element (class, datatype, individual, property, and vocabulary)
 is defined in a distinct file.
 
@@ -359,3 +378,84 @@ RpsType specifies the type of a hand shape.
 - rock: A closed fist.
 - scissors: Two fingers extended, forming a V shape.
 ```
+
+## Writing style for consistent documentation
+
+To ensure clear and consistent documentation generation, follow these
+recommendations when writing paragraph text and incorporating links.
+
+- **Avoid overly long paragraphs.**
+  Breaking up text into smaller paragraphs, using bullet points, or creating numbered lists can significantly improve readability and comprehension by separating distinct concepts, processes, criteria, or categories.
+  This makes the specification easier to scan and understand.
+
+- **Avoid bare URLs.**
+  Always provide a descriptive label for each link. Avoid using bare URLs.
+  This improves accessibility for screen readers and provides context for
+  users.
+
+  Here's an example of a **recommended** link using descriptive text:
+
+  ```Markdown
+  [SPDX Project](https://spdx.dev/)
+  ```
+
+  Here's an example of a **not recommended** bare URL:
+
+  ```Markdown
+  https://spdx.dev/
+  ```
+
+- **Bare URLs: Use with caution.**
+  While descriptive link text is generally preferred for better readability
+  and accessibility, there may be specific cases where bare URLs might be
+  necessary, such as for URLs intended to be clearly visible in both digital
+  and print formats.
+
+  Be aware that not all Markdown renderers, including MkDocs, will
+  automatically convert bare URLs into clickable links.
+  To ensure that URLs remain clickable on the specification website,
+  you should enclose them within angle brackets (`<` and `>`).
+
+  Here's an example of a **correct** bare link with a markup:
+
+  ```Markdown
+  SPDX Project GitHub: <https://github.com/spdx/>
+  ```
+
+  Here's an example of an **incorrect** bare URL:
+
+  ```Markdown
+  SPDX Project GitHub: https://github.com/spdx
+  ```
+
+- **Formatting Links to RFCs:** When referencing RFCs (Request for Comments) or other relevant IETF documents, utilize the following format for the URL:
+
+  ```text
+  https://datatracker.ietf.org/doc/<rfc-number>/
+  ```
+
+  Here's an example of a **correct** link to an RFC:
+
+  ```Markdown
+  [RFC 3986](https://datatracker.ietf.org/doc/rfc3986/)
+  ```
+
+  Here are examples of **incorrect** links to RFCs:
+
+  Missing trailing slash:
+
+  ```Markdown
+  [RFC 3986](https://datatracker.ietf.org/doc/rfc3986)
+  ```
+
+  Linking to HTML version:
+
+  ```Markdown
+  [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
+  ```
+
+  Using a different website:
+
+  ```Markdown
+  [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986)
+  ```

From ff2fa699ce5f62a9de6173cf2e1485f3d0691773 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 6 Nov 2024 10:17:38 +0000
Subject: [PATCH 11/18] Add localisation and localisation example

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 235 ++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 173 insertions(+), 62 deletions(-)

diff --git a/specmark.md b/specmark.md
index 6a30382f9..8e223c131 100644
--- a/specmark.md
+++ b/specmark.md
@@ -8,12 +8,17 @@ SPDX-License-Identifier: Community-Spec-1.0
 The SPDX 3 model is written in a constrained subset of a Markdown markup
 language*, with predefined headings.
 
-This document provides guidelines for writing model files in the specific syntax used by SPDX 3.
+This document provides guidelines for writing model files in the specific
+syntax used by SPDX 3.
+
+Following these guidelines ensures consistency and avoids rendering issues when
+using spec-parser and MkDocs to generate model ontologies and model textual
+specifications.
 
 ## Table of contents
 
 - [Overview](#overview)
-- [Model file content structure](#model-file-content-structure)
+- [Model file content structure and formatting](#model-file-content-structure-and-formatting)
 - [Model file organisation](#model-file-organisation)
 - [Syntax](#syntax)
   - [Classes](#classes)
@@ -23,6 +28,8 @@ This document provides guidelines for writing model files in the specific syntax
   - [Vocabularies](#vocabularies)
 - [Example](#example)
 - [Writing style for consistent documentation](#writing-style-for-consistent-documentation)
+- [Localisation](#localisation)
+  - [Localisation example](#localisation-example)
 
 ## Overview
 
@@ -35,7 +42,7 @@ generation of a machine-readable specification, in
 data model, by the [spec-parser](https://github.com/spdx/spec-parser/).
 
 For instance, a summary listed under the "Summary" heading will be represented
-as an `rdfs:comment` in the RDF file. Likewise, a value specified for the
+as a `rdfs:comment` in the RDF file. Likewise, a value specified for the
 "minCount" of a property name under the "Properties" heading will be
 translated into a `sh:minCount` in the RDF file. See [an example](#example).
 
@@ -51,7 +58,7 @@ as it is used by [MkDocs](https://www.mkdocs.org/) site generator.
 It differs slightly from
 [GitHub Flavored Markdown Spec](https://github.github.com/gfm/).
 
-## Model file content structure
+## Model file content structure and formatting
 
 Each model file must adhere to a strict content structure:
 
@@ -63,16 +70,20 @@ Each model file must adhere to a strict content structure:
   H1 heading containing the element's name.
 - Each element type has a predefined set of [allowed H2 headings](#syntax) and
   labeled lists that must be used to structure its content.
-- There must be a blank line before and after a heading.
-- There must be a blank line before the beginning of a list.
-- There must be a blank line after the end of a list.
-- Any block level elements nested in a list, including paragraphs, sub-lists,
-  blockquotes, code blocks, etc., must always be indented by at least 4
-  spaces for each level of nesting.
 
-The last four points are because of
-MkDocs' [strict processing](https://python-markdown.github.io/#differences)
-of Markdown files.
+Additionally, since MkDocs uses a strict
+[Python-Markdown](https://python-markdown.github.io/#differences),
+each model file must adhere to specific formatting guidelines:
+
+- Blank lines:
+  - There must be a blank line before and after a heading.
+  - There must be a blank line before and after a list.
+- Indentation:
+  - Use spaces instead of tabs.
+  - When a list item consists of multiple paragraphs, each subsequent paragraph
+    in a list item must be indented by 4 spaces. This applies to any
+    block-level elements nested in a list, including paragraphs, sub-lists,
+    blockquotes, code blocks, etc.
 
 ## Model file organisation
 
@@ -385,77 +396,177 @@ To ensure clear and consistent documentation generation, follow these
 recommendations when writing paragraph text and incorporating links.
 
 - **Avoid overly long paragraphs.**
-  Breaking up text into smaller paragraphs, using bullet points, or creating numbered lists can significantly improve readability and comprehension by separating distinct concepts, processes, criteria, or categories.
-  This makes the specification easier to scan and understand.
+    Breaking up text into smaller paragraphs, using bullet points, or creating numbered lists can significantly improve readability and comprehension by separating distinct concepts, processes, criteria, or categories.
+    This makes the specification easier to scan and understand.
 
 - **Avoid bare URLs.**
-  Always provide a descriptive label for each link. Avoid using bare URLs.
-  This improves accessibility for screen readers and provides context for
-  users.
+    Always provide a descriptive label for each link. Avoid using bare URLs.
+    This improves accessibility for screen readers and provides context for
+    users.
 
-  Here's an example of a **recommended** link using descriptive text:
+    Here's an example of a **recommended** link using descriptive text:
 
-  ```Markdown
-  [SPDX Project](https://spdx.dev/)
-  ```
+    ```Markdown
+    [SPDX Project](https://spdx.dev/)
+    ```
 
-  Here's an example of a **not recommended** bare URL:
+    Here's an example of a **not recommended** bare URL:
 
-  ```Markdown
-  https://spdx.dev/
+    ```Markdown
+    https://spdx.dev/
   ```
 
 - **Bare URLs: Use with caution.**
-  While descriptive link text is generally preferred for better readability
-  and accessibility, there may be specific cases where bare URLs might be
-  necessary, such as for URLs intended to be clearly visible in both digital
-  and print formats.
+    While descriptive link text is generally preferred for better readability
+    and accessibility, there may be specific cases where bare URLs might be
+    necessary, such as for URLs intended to be clearly visible in both digital
+    and print formats.
 
-  Be aware that not all Markdown renderers, including MkDocs, will
-  automatically convert bare URLs into clickable links.
-  To ensure that URLs remain clickable on the specification website,
-  you should enclose them within angle brackets (`<` and `>`).
+    Be aware that not all Markdown renderers, including MkDocs, will
+    automatically convert bare URLs into clickable links.
+    To ensure that URLs remain clickable on the specification website,
+    you should enclose them within angle brackets (`<` and `>`).
 
-  Here's an example of a **correct** bare link with a markup:
+    Here's an example of a **correct** bare link with a markup:
 
-  ```Markdown
-  SPDX Project GitHub: <https://github.com/spdx/>
-  ```
+    ```Markdown
+    SPDX Project GitHub: <https://github.com/spdx/>
+    ```
 
-  Here's an example of an **incorrect** bare URL:
+    Here's an example of an **incorrect** bare URL:
 
-  ```Markdown
-  SPDX Project GitHub: https://github.com/spdx
-  ```
+    ```Markdown
+    SPDX Project GitHub: https://github.com/spdx
+    ```
 
-- **Formatting Links to RFCs:** When referencing RFCs (Request for Comments) or other relevant IETF documents, utilize the following format for the URL:
+- **Standard format for RFC URLs.**
+    When referencing RFCs (Request for Comments) or other relevant IETF
+    documents, utilize the following format for the URL:
 
-  ```text
-  https://datatracker.ietf.org/doc/<rfc-number>/
-  ```
+    ```text
+    https://datatracker.ietf.org/doc/<number>/
+    ```
 
-  Here's an example of a **correct** link to an RFC:
+    Here's an example of a **correct** link to an RFC:
 
-  ```Markdown
-  [RFC 3986](https://datatracker.ietf.org/doc/rfc3986/)
-  ```
+    ```Markdown
+    [RFC 3986](https://datatracker.ietf.org/doc/rfc3986/)
+    ```
 
-  Here are examples of **incorrect** links to RFCs:
+    Here are examples of **incorrect** links to RFCs:
 
-  Missing trailing slash:
+    Incorrect. Missing trailing slash:
 
-  ```Markdown
-  [RFC 3986](https://datatracker.ietf.org/doc/rfc3986)
-  ```
+    ```Markdown
+    [RFC 3986](https://datatracker.ietf.org/doc/rfc3986)
+    ```
 
-  Linking to HTML version:
+    Incorrect. Linking to HTML version:
 
-  ```Markdown
-  [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
-  ```
+    ```Markdown
+    [RFC 3986](https://datatracker.ietf.org/doc/html/rfc3986)
+    ```
 
-  Using a different website:
+    Incorrect. Using a different website:
 
-  ```Markdown
-  [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986)
-  ```
+    ```Markdown
+    [RFC 3986](https://www.rfc-editor.org/rfc/rfc3986)
+    ```
+
+- **Code Highlighting.**
+    When using code blocks, specify the appropriate computer language code.
+    For instance, use `json` for JSON, `yaml` for YAML, and `text` for plain
+    text. This ensures correct syntax highlighting and improves readability.
+
+    For example, start a code block for JSON data with this markup:
+
+    ```markdown
+    ```json
+    ```
+
+    Here's an example of a code block with a specified language and syntax
+    highlighting:
+
+    ```json
+    {
+      "type": "Relationship",
+      "from": "urn:spdx.dev:28984",
+      "to": ["urn:acme-4.2"]
+    }
+    ```
+
+    Here's an example of a code block without a specified language and no syntax highlighting:
+
+    ```text
+    {
+      "type": "Relationship",
+      "from": "urn:spdx.dev:28984",
+      "to": ["urn:acme-4.2"]
+    }
+    ```
+
+## Localisation
+
+Only model summaries, descriptions, and vocabulary entry descriptions can be
+translated.
+
+Other content, such as model metadata, cannot be translated.
+
+To add translations, include them directly at the end of the model file
+using the same heading name followed by a two- or three-character language tag
+e.g., `## Summary @ga` for a summary in Irish language and
+`## Entries @kok` for an entry list in Konkani language.
+
+These textual descriptions are encoded as RDF 1.1 literals,
+so the language tag must adhere to the well-formedness rules outlined in
+[IETF BCP 47](https://datatracker.ietf.org/doc/html/rfc5646).
+
+### Localisation example
+
+Here's an example of an `AnnotationType` class,
+demonstrating how to add a translation for Japanese.
+Note that the "Metadata" heading remains untranslated:
+
+```markdown
+SPDX-License-Identifier: Community-Spec-1.0
+
+# AnnotationType
+
+## Summary
+
+Specifies the type of an annotation.
+
+## Description
+
+AnnotationType specifies the type of an annotation.
+
+## Metadata
+
+- name: AnnotationType
+
+## Entries
+
+- review: Used when someone reviews the Element.
+
+## Summary @ja
+
+注釈の種類を指定します。
+
+## Description @ja
+
+AnnotationType は、注釈の種類を指定します。  
+
+## Entries @ja
+
+- review: 誰かが Element をレビューし、注釈をつけたときに使われます。  
+```
+
+The above model Markdown file will generate the following RDF
+(showing partial):
+
+```ttl
+<https://spdx.org/rdf/3.0.1/terms/Core/AnnotationType> a owl:Class;
+    rdfs:comment "Specifies the type of an annotation."@en ;
+    rdfs:comment "注釈の種類を指定します。"@ja ;
+    .
+```

From 319fb4484c8b1ddf4d97fda4997ad24945673152 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 6 Nov 2024 10:21:33 +0000
Subject: [PATCH 12/18] Add notes on ja example authorship

The Japanese example in this documentation is by @NorioKobota

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
Co-Authored-By: Norio Kobota <8510920+noriokobota@users.noreply.github.com>
---
 specmark.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/specmark.md b/specmark.md
index 8e223c131..375e34429 100644
--- a/specmark.md
+++ b/specmark.md
@@ -554,11 +554,11 @@ AnnotationType specifies the type of an annotation.
 
 ## Description @ja
 
-AnnotationType は、注釈の種類を指定します。  
+AnnotationType は、注釈の種類を指定します。
 
 ## Entries @ja
 
-- review: 誰かが Element をレビューし、注釈をつけたときに使われます。  
+- review: 誰かが Element をレビューし、注釈をつけたときに使われます。
 ```
 
 The above model Markdown file will generate the following RDF

From c488321ba4da356676df5c83e857ea14ba75166c Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 6 Nov 2024 14:59:46 +0000
Subject: [PATCH 13/18] Revise code block language code

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/specmark.md b/specmark.md
index 375e34429..1fb5ca8b9 100644
--- a/specmark.md
+++ b/specmark.md
@@ -478,14 +478,14 @@ recommendations when writing paragraph text and incorporating links.
     For instance, use `json` for JSON, `yaml` for YAML, and `text` for plain
     text. This ensures correct syntax highlighting and improves readability.
 
-    For example, start a code block for JSON data with this markup:
+    For example, start a JSON code block with this markup:
 
     ```markdown
     ```json
     ```
 
-    Here's an example of a code block with a specified language and syntax
-    highlighting:
+    A code block with a specified language will be rendered with syntax
+    highlighting, appearing as follows:
 
     ```json
     {
@@ -495,7 +495,8 @@ recommendations when writing paragraph text and incorporating links.
     }
     ```
 
-    Here's an example of a code block without a specified language and no syntax highlighting:
+    A code block without a specified language will be rendered without syntax
+    highlighting, appearing as follows:
 
     ```text
     {

From a4a77e2be94f437d0e352bbc4caf08c6ba5b8927 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 6 Nov 2024 15:11:54 +0000
Subject: [PATCH 14/18] Reorg TOC

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 77 +++++++++++++++++++++++++++--------------------------
 1 file changed, 39 insertions(+), 38 deletions(-)

diff --git a/specmark.md b/specmark.md
index 1fb5ca8b9..d7900d7a1 100644
--- a/specmark.md
+++ b/specmark.md
@@ -18,16 +18,16 @@ specifications.
 ## Table of contents
 
 - [Overview](#overview)
-- [Model file content structure and formatting](#model-file-content-structure-and-formatting)
-- [Model file organisation](#model-file-organisation)
+- [Directory organisation](#directory-organisation)
+- [File content structure and formatting](#file-content-structure-and-formatting)
+  - [Model file example](#model-file-example)
 - [Syntax](#syntax)
   - [Classes](#classes)
   - [Datatypes](#datatypes)
   - [Individuals](#individuals)
   - [Properties](#properties)
   - [Vocabularies](#vocabularies)
-- [Example](#example)
-- [Writing style for consistent documentation](#writing-style-for-consistent-documentation)
+- [Writing style](#writing-style)
 - [Localisation](#localisation)
   - [Localisation example](#localisation-example)
 
@@ -58,34 +58,7 @@ as it is used by [MkDocs](https://www.mkdocs.org/) site generator.
 It differs slightly from
 [GitHub Flavored Markdown Spec](https://github.github.com/gfm/).
 
-## Model file content structure and formatting
-
-Each model file must adhere to a strict content structure:
-
-- All files must be encoded in UTF-8.
-- Each file must start with SPDX license information:
-  `SPDX-License-Identifier: Community-Spec-1.0`
-  and follows by one blank line.
-- The content immediately after the license information must begin with an
-  H1 heading containing the element's name.
-- Each element type has a predefined set of [allowed H2 headings](#syntax) and
-  labeled lists that must be used to structure its content.
-
-Additionally, since MkDocs uses a strict
-[Python-Markdown](https://python-markdown.github.io/#differences),
-each model file must adhere to specific formatting guidelines:
-
-- Blank lines:
-  - There must be a blank line before and after a heading.
-  - There must be a blank line before and after a list.
-- Indentation:
-  - Use spaces instead of tabs.
-  - When a list item consists of multiple paragraphs, each subsequent paragraph
-    in a list item must be indented by 4 spaces. This applies to any
-    block-level elements nested in a list, including paragraphs, sub-lists,
-    blockquotes, code blocks, etc.
-
-## Model file organisation
+## Directory organisation
 
 Apart from the content in each individual file, the file itself has to be
 placed in a specific location, as the spec-parser implies some model semantic
@@ -130,7 +103,34 @@ The living repository at
 <https://github.com/spdx/spdx-3-model/tree/main/model>
 is the best reference.
 
-## Example
+## File content structure and formatting
+
+Each model file must adhere to a strict content structure:
+
+- All files must be encoded in UTF-8.
+- Each file must start with SPDX license information:
+  `SPDX-License-Identifier: Community-Spec-1.0`
+  and follows by one blank line.
+- The content immediately after the license information must begin with an
+  H1 heading containing the element's name.
+- Each element type has a predefined set of [allowed H2 headings](#syntax) and
+  labeled lists that must be used to structure its content.
+
+Additionally, since MkDocs uses a strict
+[Python-Markdown](https://python-markdown.github.io/#differences),
+each model file must adhere to specific formatting guidelines:
+
+- Blank lines:
+  - There must be a blank line before and after a heading.
+  - There must be a blank line before and after a list.
+- Indentation:
+  - Use spaces instead of tabs.
+  - When a list item consists of multiple paragraphs, each subsequent paragraph
+    in a list item must be indented by 4 spaces. This applies to any
+    block-level elements nested in a list, including paragraphs, sub-lists,
+    blockquotes, code blocks, etc.
+
+### Model file example
 
 This example is taken from the actual file for
 [SimpleLicensingText](https://github.com/spdx/spdx-3-model/blob/main/model/SimpleLicensing/Classes/SimpleLicensingText.md?plain=1)
@@ -390,7 +390,7 @@ RpsType specifies the type of a hand shape.
 - scissors: Two fingers extended, forming a V shape.
 ```
 
-## Writing style for consistent documentation
+## Writing style
 
 To ensure clear and consistent documentation generation, follow these
 recommendations when writing paragraph text and incorporating links.
@@ -422,18 +422,19 @@ recommendations when writing paragraph text and incorporating links.
     necessary, such as for URLs intended to be clearly visible in both digital
     and print formats.
 
-    Be aware that not all Markdown renderers, including MkDocs, will
-    automatically convert bare URLs into clickable links.
+    Be aware that MkDocs *will not* automatically convert bare URLs into
+    clickable links.
+
     To ensure that URLs remain clickable on the specification website,
     you should enclose them within angle brackets (`<` and `>`).
 
-    Here's an example of a **correct** bare link with a markup:
+    Here's an example of a **clickable** URL:
 
     ```Markdown
     SPDX Project GitHub: <https://github.com/spdx/>
     ```
 
-    Here's an example of an **incorrect** bare URL:
+    Here's an example of an **unclickable** URL:
 
     ```Markdown
     SPDX Project GitHub: https://github.com/spdx

From 5f861da091b4ab4503e918c8b0299f57e5f59fbc Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 13 Nov 2024 07:02:48 +0000
Subject: [PATCH 15/18] Add note on IRI in Metadata section

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 22 +++++++++++++++++-----
 1 file changed, 17 insertions(+), 5 deletions(-)

diff --git a/specmark.md b/specmark.md
index d7900d7a1..9e940f8ea 100644
--- a/specmark.md
+++ b/specmark.md
@@ -44,7 +44,8 @@ data model, by the [spec-parser](https://github.com/spdx/spec-parser/).
 For instance, a summary listed under the "Summary" heading will be represented
 as a `rdfs:comment` in the RDF file. Likewise, a value specified for the
 "minCount" of a property name under the "Properties" heading will be
-translated into a `sh:minCount` in the RDF file. See [an example](#example).
+translated into a `sh:minCount` in the RDF file.
+See [an example](#model-file-example).
 
 Descriptions provided under the "Description" heading are intended for human
 reference and will not be incorporated into the RDF file.
@@ -414,13 +415,24 @@ recommendations when writing paragraph text and incorporating links.
 
     ```Markdown
     https://spdx.dev/
-  ```
+    ```
 
 - **Bare URLs: Use with caution.**
     While descriptive link text is generally preferred for better readability
-    and accessibility, there may be specific cases where bare URLs might be
-    necessary, such as for URLs intended to be clearly visible in both digital
-    and print formats.
+    and accessibility,
+    there may be specific instances where bare URLs might be necessary.
+    This could include cases where URLs need to be clearly visible in both
+    digital and print formats or when the URL serves as a metadata value.
+
+    The IRI field in the Metadata section MUST use a bare URL:
+
+    ```markdown
+    ## Metadata
+
+    - name: SpdxOrganization
+    - type: Organization
+    - IRI: https://spdx.org/
+    ```
 
     Be aware that MkDocs *will not* automatically convert bare URLs into
     clickable links.

From ae1453c8824b4984aa724839986383b43a1e9107 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 13 Nov 2024 09:25:28 +0000
Subject: [PATCH 16/18] Add examples of RFC 5646 language tag

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 specmark.md | 58 ++++++++++++++++++++++++++++++++++++++++++++---------
 1 file changed, 48 insertions(+), 10 deletions(-)

diff --git a/specmark.md b/specmark.md
index 9e940f8ea..c15fe677b 100644
--- a/specmark.md
+++ b/specmark.md
@@ -397,10 +397,12 @@ To ensure clear and consistent documentation generation, follow these
 recommendations when writing paragraph text and incorporating links.
 
 - **Avoid overly long paragraphs.**
+
     Breaking up text into smaller paragraphs, using bullet points, or creating numbered lists can significantly improve readability and comprehension by separating distinct concepts, processes, criteria, or categories.
     This makes the specification easier to scan and understand.
 
 - **Avoid bare URLs.**
+
     Always provide a descriptive label for each link. Avoid using bare URLs.
     This improves accessibility for screen readers and provides context for
     users.
@@ -418,6 +420,7 @@ recommendations when writing paragraph text and incorporating links.
     ```
 
 - **Bare URLs: Use with caution.**
+
     While descriptive link text is generally preferred for better readability
     and accessibility,
     there may be specific instances where bare URLs might be necessary.
@@ -453,6 +456,7 @@ recommendations when writing paragraph text and incorporating links.
     ```
 
 - **Standard format for RFC URLs.**
+
     When referencing RFCs (Request for Comments) or other relevant IETF
     documents, utilize the following format for the URL:
 
@@ -487,6 +491,7 @@ recommendations when writing paragraph text and incorporating links.
     ```
 
 - **Code Highlighting.**
+
     When using code blocks, specify the appropriate computer language code.
     For instance, use `json` for JSON, `yaml` for YAML, and `text` for plain
     text. This ensures correct syntax highlighting and improves readability.
@@ -527,19 +532,25 @@ translated.
 Other content, such as model metadata, cannot be translated.
 
 To add translations, include them directly at the end of the model file
-using the same heading name followed by a two- or three-character language tag
-e.g., `## Summary @ga` for a summary in Irish language and
-`## Entries @kok` for an entry list in Konkani language.
-
-These textual descriptions are encoded as RDF 1.1 literals,
-so the language tag must adhere to the well-formedness rules outlined in
-[IETF BCP 47](https://datatracker.ietf.org/doc/html/rfc5646).
+using the same set of heading names followed by a language tag (e.g.,
+`## Summary @ga` for a summary in Irish,
+`## Description @kok` for a description in Konkani, or
+`## Entries @sr-Latn` for an entry list in Serbian written using
+the Latin script).
+
+These textual descriptions are encoded as RDF 1.1 literals.
+Therefore, the language tag used to identify the language must follow the
+well-formedness rules defined in
+[IETF BCP 47 (RFC 5646)](https://datatracker.ietf.org/doc/rfc5646).
+Appendix A of that document provides examples of valid language tags.
 
 ### Localisation example
 
-Here's an example of an `AnnotationType` class,
-demonstrating how to add a translation for Japanese.
-Note that the "Metadata" heading remains untranslated:
+Here's an example of an `AnnotationType` class with translations for Japanese,
+Chinese (simplified script), and Chinese (traditional script).
+
+Note that the "Metadata" section and the names of entries within the "Entries"
+section remain untranslated:
 
 ```markdown
 SPDX-License-Identifier: Community-Spec-1.0
@@ -573,6 +584,31 @@ AnnotationType は、注釈の種類を指定します。
 ## Entries @ja
 
 - review: 誰かが Element をレビューし、注釈をつけたときに使われます。
+
+## Summary @zh-Hans
+
+指定注释的类型。
+
+## Description @zh-Hans
+
+AnnotationType指定注释的类型。
+
+## Entries @zh-Hans
+
+- review: 当其人评审元素时使用的注释。
+
+## Summary @zh-Hant
+
+指定註解的類型。
+
+## Description @zh-Hant
+
+AnnotationType指定註解的類型。
+
+## Entries @zh-Hant
+
+- review: 當其人審核元素時使用的註解。
+
 ```
 
 The above model Markdown file will generate the following RDF
@@ -582,5 +618,7 @@ The above model Markdown file will generate the following RDF
 <https://spdx.org/rdf/3.0.1/terms/Core/AnnotationType> a owl:Class;
     rdfs:comment "Specifies the type of an annotation."@en ;
     rdfs:comment "注釈の種類を指定します。"@ja ;
+    rdfs:comment "指定注释的类型。"@zh-Hans ;
+    rdfs:comment "指定註解的類型。"@zh-Hant ;
     .
 ```

From 1267fc405a63d2800de6938ac751d3de96a9940a Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 13 Nov 2024 18:16:27 +0000
Subject: [PATCH 17/18] Move documents to docs/

Also break Localisation section to translation.md

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 Contributing.md                   |  10 ++-
 README.md                         |  22 ++++--
 specmark.md => docs/format.md     | 103 ++-------------------------
 Glossary.md => docs/glossary.md   |   0
 model.drawio => docs/model.drawio |   0
 docs/translation.md               | 112 ++++++++++++++++++++++++++++++
 6 files changed, 142 insertions(+), 105 deletions(-)
 rename specmark.md => docs/format.md (84%)
 rename Glossary.md => docs/glossary.md (100%)
 rename model.drawio => docs/model.drawio (100%)
 create mode 100644 docs/translation.md

diff --git a/Contributing.md b/Contributing.md
index ee2c7b8a7..6b8458bb4 100644
--- a/Contributing.md
+++ b/Contributing.md
@@ -10,7 +10,8 @@ and during our [regular meetings][meetings].
 
 All the details are in: <https://spdx.dev/participate/tech/>
 
-This repository consists of Markdown files describing the model classes,
+This repository consists of files written in
+[a specific Markdown format][format] describing the model classes,
 datatypes, properties, and vocabularies which will be used to automatically
 create documentation, ontologies, and validation artifacts.
 These are organized by profile.
@@ -54,6 +55,11 @@ updating individual profiles.
 
 This method of development was agreed upon by the SPDX Tech team on 2023-01-17.
 
+## Translation
+
+Translations of model descriptions are welcome.
+Please see [translation.md][translation] for details.
+
 ## Profile Maintainers
 
 In accordance with the development model described above,
@@ -76,6 +82,8 @@ Each profile in active development phase also has their own
 | Security | [Thomas Steenbergen][gh-thomas], [Adolfo García Veytia][gh-adolfo], and [Rose Judge][gh-rose] |
 | Software | [Alexios Zavras][gh-alexios] and [Gary O'Neall][gh-gary] |
 
+[format]: ./docs/format.md
+[translation]: ./docs/translation.md
 [spdx-tech-list]: https://lists.spdx.org/mailman/listinfo/spdx-tech
 [meetings]: https://github.com/spdx/meetings/
 [issues]: https://github.com/spdx/spdx-3-model/issues/
diff --git a/README.md b/README.md
index 53f28c370..deccc7b28 100644
--- a/README.md
+++ b/README.md
@@ -17,11 +17,14 @@ standard.
 
 ## Branches and Formats
 
-The editable files inside `model/` directory are written in a 
-[constrained subset of Markdown](./specmark.md),
+The editable files inside `model/` directory are written in a
+[constrained subset of Markdown][format],
 with specific headings for specific types of information,
 and are stored in the `main` branch.
 
+Textual description of these model files
+[can be translated][translation] into other natural languages.
+
 The editable files are automatically processed by
 [spec-parser](https://github.com/spdx/spec-parser/)
 and the following are generated:
@@ -35,7 +38,7 @@ and the following are generated:
   - [Turtle format](https://en.wikipedia.org/wiki/Turtle_(syntax)):
     [spdx-model.ttl](https://spdx.org/rdf/3.0.1/spdx-model.ttl)
   - [JSON-LD format](https://json-ld.org/):
-    [spdx-model.jsonld](https://spdx.github.io/spdx-spec/v3.0.1/rdf/spdx-model.jsonld) 
+    [spdx-model.jsonld](https://spdx.github.io/spdx-spec/v3.0.1/rdf/spdx-model.jsonld)
 
 People who wish to read the current version of the information
 should be viewing the generated files, while anyone wanting to edit
@@ -48,7 +51,8 @@ For the specification content other than the model, they are in the
 
 The SPDX model is described using profiles related to the software application.
 The profiles are organized as sub-directories under the ‘model’ directory.
-The model diagram is available in [model.drawio](./model.drawio) file.
+
+The model diagram is available in [model.drawio][model-diagram] file.
 
 Note:
 
@@ -121,7 +125,11 @@ snippets, and artifacts of the software application.
 
 See [CHANGELOG.md](CHANGELOG.md) for changes between versions.
 
-## Contribute!
+## Glossary
+
+See [glossary][glossary] for definitions and explanations of terms used throughout the specification.
+
+## Contribute
 
 For information about how to contribute to a specific profile,
 please see [Contributing.md](Contributing.md).
@@ -134,5 +142,9 @@ and during our [regular meetings][meetings].
 
 All the details are in: <https://spdx.dev/participate/tech/>
 
+[format]: ./docs/format.md
+[translation]: ./docs/translation.md
+[model-diagram]: ./docs/model.drawio
+[glossary]: ./docs/glossary.md
 [meetings]: https://github.com/spdx/meetings/
 [spdx-tech-list]: https://lists.spdx.org/mailman/listinfo/spdx-tech
diff --git a/specmark.md b/docs/format.md
similarity index 84%
rename from specmark.md
rename to docs/format.md
index c15fe677b..a1699d65f 100644
--- a/specmark.md
+++ b/docs/format.md
@@ -28,8 +28,7 @@ specifications.
   - [Properties](#properties)
   - [Vocabularies](#vocabularies)
 - [Writing style](#writing-style)
-- [Localisation](#localisation)
-  - [Localisation example](#localisation-example)
+- [Translation](#translation)
 
 ## Overview
 
@@ -524,101 +523,7 @@ recommendations when writing paragraph text and incorporating links.
     }
     ```
 
-## Localisation
+## Translation
 
-Only model summaries, descriptions, and vocabulary entry descriptions can be
-translated.
-
-Other content, such as model metadata, cannot be translated.
-
-To add translations, include them directly at the end of the model file
-using the same set of heading names followed by a language tag (e.g.,
-`## Summary @ga` for a summary in Irish,
-`## Description @kok` for a description in Konkani, or
-`## Entries @sr-Latn` for an entry list in Serbian written using
-the Latin script).
-
-These textual descriptions are encoded as RDF 1.1 literals.
-Therefore, the language tag used to identify the language must follow the
-well-formedness rules defined in
-[IETF BCP 47 (RFC 5646)](https://datatracker.ietf.org/doc/rfc5646).
-Appendix A of that document provides examples of valid language tags.
-
-### Localisation example
-
-Here's an example of an `AnnotationType` class with translations for Japanese,
-Chinese (simplified script), and Chinese (traditional script).
-
-Note that the "Metadata" section and the names of entries within the "Entries"
-section remain untranslated:
-
-```markdown
-SPDX-License-Identifier: Community-Spec-1.0
-
-# AnnotationType
-
-## Summary
-
-Specifies the type of an annotation.
-
-## Description
-
-AnnotationType specifies the type of an annotation.
-
-## Metadata
-
-- name: AnnotationType
-
-## Entries
-
-- review: Used when someone reviews the Element.
-
-## Summary @ja
-
-注釈の種類を指定します。
-
-## Description @ja
-
-AnnotationType は、注釈の種類を指定します。
-
-## Entries @ja
-
-- review: 誰かが Element をレビューし、注釈をつけたときに使われます。
-
-## Summary @zh-Hans
-
-指定注释的类型。
-
-## Description @zh-Hans
-
-AnnotationType指定注释的类型。
-
-## Entries @zh-Hans
-
-- review: 当其人评审元素时使用的注释。
-
-## Summary @zh-Hant
-
-指定註解的類型。
-
-## Description @zh-Hant
-
-AnnotationType指定註解的類型。
-
-## Entries @zh-Hant
-
-- review: 當其人審核元素時使用的註解。
-
-```
-
-The above model Markdown file will generate the following RDF
-(showing partial):
-
-```ttl
-<https://spdx.org/rdf/3.0.1/terms/Core/AnnotationType> a owl:Class;
-    rdfs:comment "Specifies the type of an annotation."@en ;
-    rdfs:comment "注釈の種類を指定します。"@ja ;
-    rdfs:comment "指定注释的类型。"@zh-Hans ;
-    rdfs:comment "指定註解的類型。"@zh-Hant ;
-    .
-```
+Model summaries, descriptions, and vocabulary entry descriptions can be
+translated. Please see [translation.md](./translation.md) for details.
diff --git a/Glossary.md b/docs/glossary.md
similarity index 100%
rename from Glossary.md
rename to docs/glossary.md
diff --git a/model.drawio b/docs/model.drawio
similarity index 100%
rename from model.drawio
rename to docs/model.drawio
diff --git a/docs/translation.md b/docs/translation.md
new file mode 100644
index 000000000..60e608b8b
--- /dev/null
+++ b/docs/translation.md
@@ -0,0 +1,112 @@
+# Translation
+
+Translation of the SPDX specification.
+
+## Table of contents
+
+- [Model translation](#model-translation)
+- [Model translation example](#model-translation-example)
+
+## Model translation
+
+Only model summaries, descriptions, and vocabulary entry descriptions can be
+translated.
+
+Other content, such as model metadata, cannot be translated.
+
+To add translations, include them directly at the end of the model file
+using the [same set of heading names][headings]
+followed by a language tag (e.g.,
+`## Summary @ga` for a summary in Irish,
+`## Description @kok` for a description in Konkani, or
+`## Entries @sr-Latn` for an entry list in Serbian written using
+the Latin script).
+
+These textual descriptions are encoded as a
+["language-tagged string"][language-tagged-string] in RDF.
+Therefore, the language tag used to identify the language must follow the
+well-formedness rules defined in [IETF BCP 47 (RFC 5646)][rfc5646].
+Appendix A of that document provides examples of valid language tags.
+
+[headings]: ./format.md#syntax
+[language-tagged-string]: https://www.w3.org/TR/rdf11-concepts/#dfn-language-tagged-string
+[rfc5646]: https://datatracker.ietf.org/doc/rfc5646
+
+### Model translation example
+
+Here's an example of an `AnnotationType` vocabulary with translations for
+Japanese, Chinese (simplified script), and Chinese (traditional script).
+
+Note that the "Metadata" section and the names of entries within the "Entries"
+section remain untranslated:
+
+```markdown
+SPDX-License-Identifier: Community-Spec-1.0
+
+# AnnotationType
+
+## Summary
+
+Specifies the type of an annotation.
+
+## Description
+
+AnnotationType specifies the type of an annotation.
+
+## Metadata
+
+- name: AnnotationType
+
+## Entries
+
+- review: Used when someone reviews the Element.
+
+## Summary @ja
+
+注釈の種類を指定します。
+
+## Description @ja
+
+AnnotationType は、注釈の種類を指定します。
+
+## Entries @ja
+
+- review: 誰かが Element をレビューし、注釈をつけたときに使われます。
+
+## Summary @zh-Hans
+
+指定注释的类型。
+
+## Description @zh-Hans
+
+AnnotationType指定注释的类型。
+
+## Entries @zh-Hans
+
+- review: 当其人评审元素时使用的注释。
+
+## Summary @zh-Hant
+
+指定註解的類型。
+
+## Description @zh-Hant
+
+AnnotationType指定註解的類型。
+
+## Entries @zh-Hant
+
+- review: 當其人審核元素時使用的註解。
+
+```
+
+The above model Markdown file will generate the following RDF
+(showing partial):
+
+```ttl
+<https://spdx.org/rdf/3.0.1/terms/Core/AnnotationType> a owl:Class;
+    rdfs:comment "Specifies the type of an annotation."@en ;
+    rdfs:comment "注釈の種類を指定します。"@ja ;
+    rdfs:comment "指定注释的类型。"@zh-hans ;
+    rdfs:comment "指定註解的類型。"@zh-hant ;
+    .
+```

From aa008d30f6c32dcbbc06b2ed16d16789a53a1433 Mon Sep 17 00:00:00 2001
From: Arthit Suriyawongkul <arthit@gmail.com>
Date: Wed, 13 Nov 2024 18:27:53 +0000
Subject: [PATCH 18/18] Add notes on language tag sorting

Signed-off-by: Arthit Suriyawongkul <arthit@gmail.com>
---
 docs/translation.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/docs/translation.md b/docs/translation.md
index 60e608b8b..5853208b3 100644
--- a/docs/translation.md
+++ b/docs/translation.md
@@ -35,7 +35,8 @@ Appendix A of that document provides examples of valid language tags.
 ### Model translation example
 
 Here's an example of an `AnnotationType` vocabulary with translations for
-Japanese, Chinese (simplified script), and Chinese (traditional script).
+Japanese, Chinese (simplified script), and Chinese (traditional script),
+sorted by language tag.
 
 Note that the "Metadata" section and the names of entries within the "Entries"
 section remain untranslated: