= ISO International Classification for Standards (ICS) codes in machine-processable formats

== Purpose

ISO International Classification for Standards (ICS) codes are used amongst international standards for categorization purposes especially in ISO and IEC standards.

While ISO provides them in a PDF form for public usage, they are not available in machine-readable form.

The contents of this repository aims to provide ICS codes in machine-readable form (YAML/YAML-LD and JSON/JSON-LD).

This repository provides the following editions of the ICS codes:

• Edition 6 (published in 2005)
• Edition 7 (published in 2015)

NOTE: IEEE SA uses ICS Edition 6, while ISO and IEC use ICS Edition 7.

== Models

=== Syntax

The modelling syntax used is YAML-LD which is based on JSON-LD.

The following files are provided in this repository:

yaml/{edition}/*.yaml:: YAML-LD files for ICS codes. json/{edition}/*.json:: JSON-LD files for ICS codes.

The {edition} value is:

ed6:: ICS Edition 6 ed7:: ICS Edition 7

=== ICS code

ICS codes are made up of one to three code sections.

• The first code section represents the "field" (the "field code")
• The second is optional, represents the "group" (the "group code")
• The third is optional, represents the "subgroup" (the "subgroup code")

[example] .ICS code entry

03.100.30 has field code 03, group code 100, and subgroup code 30.

=== ICS data models

There are 3 types of ICS codes:

• Field (top-level)
• Group (second level)
• Subgroup (third level)

=== ICS code data

An ICS code represents a data structure that contains:

• Edition number (mandatory)
• Field code (mandatory)
• Group code (optional)
• Subgroup code (optional)
• Description (mandatory)
• Notes (optional), there can be multiple notes.

NOTE: In an ICS subgroup, the JSON representation provides both the description of the subgroup and of the group.

NOTE: The JSON-LD context is not yet resolvable.

[source,yaml]

'@context': https://isoics.org/ics/ns/subgroup.jsonld code: 03.100.30 description: Management of human resources descriptionFull: ... edition: 7 fieldcode: "03" groupcode: "100" notes:

• ... subgroupcode: "30"

=== ICS note

Each ICS note contains:

• A textual portion
• One or more links to other ICS codes. The position of the linked code is given within the textual portion

Example without link:

[source,yaml]

text: Including staff training, staff responsibilities, staff qualifications and certification

[source,json]

{ "text": "Including staff training, staff responsibilities," "staff qualifications and certification" }

Example with link:

[source,yaml]

ics-code: 25.160.01 text: Welding, brazing and soldering in general, see {ics-code}

[source,json]

{ "text": "Welding, brazing and soldering in general, see {ics-code}", "ics-code": "25.160.01" }

== YAML ICS

This is an example of an ICS entry in this repository.

https://github.com/metanorma/iso-ics-codes/blob/main/yaml/ed7/03_100_30.yaml

[source,yaml]

'@context': https://isoics.org/ics/ns/subgroup.jsonld code: 03.100.30 description: Management of human resources descriptionFull: Services. Company organization, management and quality. Administration. Transport. Sociology. Company organization and management. Management systems. Management of human resources. edition: 7 fieldcode: "03" groupcode: "100" notes:

• text: Including staff training, staff responsibilities, staff qualifications and certification

• ics-code: 25.160.01 text: Welding, brazing and soldering in general, see {ics-code} subgroupcode: "30"

== JSON ICS

This is an example of an ICS entry in this repository.

https://github.com/metanorma/iso-ics-codes/blob/main/json/ed7/03_100_30.json

[source,json]

{ "@context": "https://isoics.org/ics/ns/subgroup.jsonld", "code": "03.100.30", "description": "Management of human resources", "descriptionFull": "Services. Company organization, management and quality. Administration. Transport. Sociology. Company organization and management. Management systems. Management of human resources.", "edition": 7, "fieldcode": "03", "groupcode": "100", "notes": [ { "text": "Including staff training, staff responsibilities, staff qualifications and certification" }, { "text": "Welding, brazing and soldering in general, see {ics-code}", "ics-code": "25.160.01" } ], "subgroupcode": "30" }

== Usage

=== General

Files are directly named using the ICS codes in order to enable machine access for the data related to every single ICS code.

For clarity, the "fullstop" symbol is replaced with an underscore in a filename.

For example,

• 01.json contains data of ICS code 01 (field code 01)
• 01_020.json contains data of ICS code 01.020 (field code 01, group code 020)
• 01_040_01.json contains data of ICS code 01.040.01 (field code 01, group code 040, subgroup code 01)

=== Data conversion

The following scripts can be used to generate JSON files from YAML (and vice versa).

To generate JSON-LD files from YAML:

[source,sh]

for f in $(find yaml -name '*.yaml' | sort); do yq -P -j '.' $f > ${f//yaml/json}; done

To generate YAML-LD files from JSON:

[source,sh]

for f in $(find json -name '*.json' | sort); do yq -P '.' $f > ${f//json/yaml}; done

== Development

=== General

When adding data to the authoritative YAML files under yaml/{edition}, we will need to ensure that the YAML files are normalized and also regenerate the JSON files.

Some make targets are provided to assist the process.

=== Normalize YAML files

[source,sh]

make normalize

=== Check what YAML files are not normalized

This target depends on normalize.diff.

[source,sh]

make check-normalize

=== Detect what YAML files are not normalized

[source,sh]

make normalize.diff cat normalize.diff

=== Generate JSON files from YAML

YAML source files need to be normalized before generating the JSON equivalents.

[source,sh]

make json-all

WARNING: Please run make normalize before make json-all to ensure YAML sources are normalized.

== Data source

=== Edition 7

The data source is the 2015 edition of ISO ICS, which are also available from the ISO https://www.iso.org/standards-catalogue/browse-by-ics.html["`Browse by ICS`"] interface.

These files are created by using scripts located in https://github.com/metanorma/iso-ics-codes-scripts[`iso-ics-codes-scripts`].

=== Edition 6

The data source is the 2005 edition of ISO ICS, available as a PDF under reference-docs/ICS_ISO_Ed_6_2005_en.pdf.

== Credits

This code list is maintained by https://www.metanorma.org[Ribose Metanorma].

== License

The code here is available under the terms of the http://opensource.org/licenses/MIT[MIT License].

The source data belongs to https://www.iso.org[ISO].