<commit_before>FORMAT: 1A

# Common Terms Registry API
The Common Terms Registry API is a tool to allow developers to find and reuse common terms that describe user needs and preferences, and to contribute new standard terms and aliases not already included in the Common Terms Registry.

This document describes the REST API available to developers.

# Data Objects
This section describes the data objects which are accepted by and returned by the Common Terms Registry API.

## Record
All records in the Common Terms Registry have the following common fields:

|Field|Description|
| --- | --- |
|Type|The type of record, i.e. term, alias, translation, transformation, operator.|
|Permanency|An indication of how likely a field is to change over time.|
|NameSpace|The namespace to use in combination with the UniqueID to construct a URI that refers to the record.|
|UniqueId|A completely unique identifier for this record.|
|Notes|Any additional information associated with this record.|
|Status|The review status of this record.|
|Updated|The date at which the record was last updated.|

## Term
A term is a single canonical way of describing a need or solution. For example, users who require high-contrast schemes may be concerned about the ability to set a high-contrast background and foreground color. Each of these would be a common term, identified by a persistent ID such as backgroundColor or foregroundColor.  In addition to the common fields described above, term records have the following fields:

|Field|Description|
| --- | --- |
|ValueSpace|A description of the values allowed for this term.|
|TermLabel|A short label for this term as it would appear in a menu or listing.|
|Definition|A description of the term.|
|ApplicationUniqueFlag|Whether this term is unique to a particular application.|
|Uses|A description of other systems that use this term and how they use it.|

## Alias
An alias is another name for a standard term, with no other differences. When describing system settings and other user preferences, the difference may be simply a matter of formatting. For example, one program might have a registry entry or setting for max.volume and another might have a registry entry or setting called max_volume. Other examples may simply be a matter of alternate wording. For example, one developer may use “loudness” instead of “volume” when describing their settings. In addition to the common fields described above, alias records have the following fields:

|Field|Description|
| --- | --- |
|AliasOf|The unique identifier of the parent record this record is an alias of.|
|TermLabel|A short label for this term as it would appear in a menu or listing.|
|Uses|A description of other systems that use this term and how they use it.|

## Translation
A translation is representation of a term in another language with no other differences. For example, in US English, the preference for a particular background color might be presented as “backgroundColor”. In Commonwealth countries, that might be presented as “backgroundColour”. In addition to the common fields described above, translation records have the following fields:

|Field|Description|
| --- | --- |
|TranslationOf|The unique identifier of the parent record this record is a translation of.|
|ValueSpace|A translation of the terms used in the parent record’s value space.|
|TermLabel|A translation of the short label for the parent record as it would appear in a menu or listing.|
|Definition|A translation of the definition of the parent record.|
|Uses|A description of other systems that use this term and how they use it.|

## Transformation
Translations and aliases present a term using different words or formatting, with no meaningful difference in the values used to describe a user’s needs or preferences. For example, two devices may have a volume control that can be set from 0 to 10 in increments of 1. If those two devices have the same maximum volume and each of their corresponding volume levels are the same loudness, then a user who prefers (or requires) for the volume to be set to 10 would have the same experience in having that preference applied to each device. It wouldn't matter if one device called the control “volume” and the other called the control “loudness”. On the other hand, if two devices have a different maximum volume, are adjustable using different increments, or have a different perceived loudness when set to the same value, then something else is required.

For these cases, the Common Terms Registry provides a transformation. A transformation provides a bidirectional lossless algorithm for converting from one way of describing preferences and needs to another. To continue the previous example, the common term describing volume preferences might be expressed using a decibel scale. For an implementation that uses 0-10 to indicate volume, the transformation record would provide an algorithm for converting from decibel to 0-10 values and from 0-10 values to decibel values. In addition to the common fields described above, transformation records have the following fields:

|Field|Description|
| --- | --- |
|ValueSpace|A bidirectional lossless algorithm for converting to and from the values used by the common term.|
|TermLabel|A translation of the short label for the parent record as it would appear in a menu or listing.|
|Uses|A description of other systems that use this term and how they use it.|

## Operator
There are some preferences that are conditional, and depend on the environment and the content an AT user is interacting with. For example, an AT user may wish to have two different color schemes, one for daylight hours, and one for nighttime.

Operators are terms that can be used to clearly identify what settings should be applied under what circumstances.  For example, “greater than”, “less than”, and “in the following range” are all operators. The conjunctions “and”, “or” as well as the adverbs “not” and “only” are also operators. Operators can be combined to describe complex conditions.

In addition to the common fields described above, operator records have only one additional field.

|Field|Description|
| --- | --- |
|Definition|A clear definition of the operator.|

## Relationships
Terms and Operators are unique records that do not refer to another record implicitly. All other record types (aliases, translations, transformations) must refer to a single parent term (see the aliasOf, translationOf, etc. fields proposed above).

## Change Sets
Updates to existing records are moderated in the Common Terms Registry.  To manage multiple proposed updates to the same set of records, we use a change set that consists of only the differences between the proposed new record and the existing record.  A change set contains the following information.

|Field|Description|
| --- | --- |
|ChangeId|A completely unique identifier for this change set.|
|UniqueId|The unique identifier of the record to be updated.|
|Changes|The JSON data that represents the proposed changes.  Fields to be deleted are included and set to `null`.|
|Created|The date at which the change was proposed.|
|Status| Whether the change set was approved, rejected, or is still under review.  Can be set to "unreviewed", "approved", or "rejected".|
|Reviewed| The date at which the change was approved or rejected.  Undefined if the change set has not already been reviewed.|
|Author|The user proposing the changes.|
|Reviewer|The user approving or rejecting the changes.  Undefined if the change set has not already been reviewed.|

# API REST endpoints

## PUT /api/record
Creates a new unreviewed record.  If an author is supplied, gives them credit, otherwise the current user is listed as the author.  Until a new record is approved by reviewers, only the author and reviewers can see the proposed record.

+ Request (application/json}
    ```
    {
       "type": "GENERAL",
       "uniqueId": "newRecord",
       "termLabel": "New Record",
       "definition": "This is a new record.",
       "notes": "This record was created as an example."
     }
     ```

+ Response 200 (application/json)
    + Body
        ```
        {
            "ok":true,
            "message":"New record submitted."
        }
        ```

## POST /api/record
Creates a new change set by comparing the record submitted to an existing record.  If an author is supplied, gives them credit, otherwise the current user is listed as the author.  Until a change set is approved by reviewers, only the author and reviewers can see the proposed changes.

+ Request (application/json}
    ```
    {
       "uniqueId": "existingRecord",
       "definition": "This existing record needs to be updated.",
       "notes": null
     }
    ```

+ Response 200 (application/json)
    + Body
        ```
        {
            "ok":true,
            "message":"Your proposed changes have been submitted.",
            "changeId": "0069b020043147f58eeda6d72c9845f4"
        }
        ```

## DELETE /api/record/{uniqueId}{?confirm}
Proposes that a record be flagged as trashed.  If an author is supplied, gives them credit, otherwise the current user is listed as the author.  Until a change set is approved by reviewers, only the author and reviewers can see the proposed changes, and the record will remain visible to end users.
Reviewers can confirm that a record should be flagged as deleted by sending the "confirm" parameter.

+ Parameters
    + uniqueId (required, string) ... The unique identifier of a single record.
    + confirm (required, string) ... Used to confirm that a proposed deletion should be executed.  Only available to reviewers.

+ Response 200 (application/json)
    ```
    {
        "ok": true,
        "message": "Record flagged for deletion."
    }
    ```
<commit_msg>Fixing double-indented code blocks.<commit_after>FORMAT: 1A

# Common Terms Registry API
The Common Terms Registry API is a tool to allow developers to find and reuse common terms that describe user needs and preferences, and to contribute new standard terms and aliases not already included in the Common Terms Registry.

This document describes the REST API available to developers.

# Data Objects
This section describes the data objects which are accepted by and returned by the Common Terms Registry API.

## Record
All records in the Common Terms Registry have the following common fields:

|Field|Description|
| --- | --- |
|Type|The type of record, i.e. term, alias, translation, transformation, operator.|
|Permanency|An indication of how likely a field is to change over time.|
|NameSpace|The namespace to use in combination with the UniqueID to construct a URI that refers to the record.|
|UniqueId|A completely unique identifier for this record.|
|Notes|Any additional information associated with this record.|
|Status|The review status of this record.|
|Updated|The date at which the record was last updated.|

## Term
A term is a single canonical way of describing a need or solution. For example, users who require high-contrast schemes may be concerned about the ability to set a high-contrast background and foreground color. Each of these would be a common term, identified by a persistent ID such as backgroundColor or foregroundColor.  In addition to the common fields described above, term records have the following fields:

|Field|Description|
| --- | --- |
|ValueSpace|A description of the values allowed for this term.|
|TermLabel|A short label for this term as it would appear in a menu or listing.|
|Definition|A description of the term.|
|ApplicationUniqueFlag|Whether this term is unique to a particular application.|
|Uses|A description of other systems that use this term and how they use it.|

## Alias
An alias is another name for a standard term, with no other differences. When describing system settings and other user preferences, the difference may be simply a matter of formatting. For example, one program might have a registry entry or setting for max.volume and another might have a registry entry or setting called max_volume. Other examples may simply be a matter of alternate wording. For example, one developer may use “loudness” instead of “volume” when describing their settings. In addition to the common fields described above, alias records have the following fields:

|Field|Description|
| --- | --- |
|AliasOf|The unique identifier of the parent record this record is an alias of.|
|TermLabel|A short label for this term as it would appear in a menu or listing.|
|Uses|A description of other systems that use this term and how they use it.|

## Translation
A translation is representation of a term in another language with no other differences. For example, in US English, the preference for a particular background color might be presented as “backgroundColor”. In Commonwealth countries, that might be presented as “backgroundColour”. In addition to the common fields described above, translation records have the following fields:

|Field|Description|
| --- | --- |
|TranslationOf|The unique identifier of the parent record this record is a translation of.|
|ValueSpace|A translation of the terms used in the parent record’s value space.|
|TermLabel|A translation of the short label for the parent record as it would appear in a menu or listing.|
|Definition|A translation of the definition of the parent record.|
|Uses|A description of other systems that use this term and how they use it.|

## Transformation
Translations and aliases present a term using different words or formatting, with no meaningful difference in the values used to describe a user’s needs or preferences. For example, two devices may have a volume control that can be set from 0 to 10 in increments of 1. If those two devices have the same maximum volume and each of their corresponding volume levels are the same loudness, then a user who prefers (or requires) for the volume to be set to 10 would have the same experience in having that preference applied to each device. It wouldn't matter if one device called the control “volume” and the other called the control “loudness”. On the other hand, if two devices have a different maximum volume, are adjustable using different increments, or have a different perceived loudness when set to the same value, then something else is required.

For these cases, the Common Terms Registry provides a transformation. A transformation provides a bidirectional lossless algorithm for converting from one way of describing preferences and needs to another. To continue the previous example, the common term describing volume preferences might be expressed using a decibel scale. For an implementation that uses 0-10 to indicate volume, the transformation record would provide an algorithm for converting from decibel to 0-10 values and from 0-10 values to decibel values. In addition to the common fields described above, transformation records have the following fields:

|Field|Description|
| --- | --- |
|ValueSpace|A bidirectional lossless algorithm for converting to and from the values used by the common term.|
|TermLabel|A translation of the short label for the parent record as it would appear in a menu or listing.|
|Uses|A description of other systems that use this term and how they use it.|

## Operator
There are some preferences that are conditional, and depend on the environment and the content an AT user is interacting with. For example, an AT user may wish to have two different color schemes, one for daylight hours, and one for nighttime.

Operators are terms that can be used to clearly identify what settings should be applied under what circumstances.  For example, “greater than”, “less than”, and “in the following range” are all operators. The conjunctions “and”, “or” as well as the adverbs “not” and “only” are also operators. Operators can be combined to describe complex conditions.

In addition to the common fields described above, operator records have only one additional field.

|Field|Description|
| --- | --- |
|Definition|A clear definition of the operator.|

## Relationships
Terms and Operators are unique records that do not refer to another record implicitly. All other record types (aliases, translations, transformations) must refer to a single parent term (see the aliasOf, translationOf, etc. fields proposed above).

## Change Sets
Updates to existing records are moderated in the Common Terms Registry.  To manage multiple proposed updates to the same set of records, we use a change set that consists of only the differences between the proposed new record and the existing record.  A change set contains the following information.

|Field|Description|
| --- | --- |
|ChangeId|A completely unique identifier for this change set.|
|UniqueId|The unique identifier of the record to be updated.|
|Changes|The JSON data that represents the proposed changes.  Fields to be deleted are included and set to `null`.|
|Created|The date at which the change was proposed.|
|Status| Whether the change set was approved, rejected, or is still under review.  Can be set to "unreviewed", "approved", or "rejected".|
|Reviewed| The date at which the change was approved or rejected.  Undefined if the change set has not already been reviewed.|
|Author|The user proposing the changes.|
|Reviewer|The user approving or rejecting the changes.  Undefined if the change set has not already been reviewed.|

# API REST endpoints

## PUT /api/record
Creates a new unreviewed record.  If an author is supplied, gives them credit, otherwise the current user is listed as the author.  Until a new record is approved by reviewers, only the author and reviewers can see the proposed record.

+ Request (application/json}

    ```
    {
       "type": "GENERAL",
       "uniqueId": "newRecord",
       "termLabel": "New Record",
       "definition": "This is a new record.",
       "notes": "This record was created as an example."
     }
     ```

+ Response 200 (application/json)
    + Body

        ```
        {
            "ok":true,
            "message":"New record submitted."
        }
        ```

## POST /api/record
Creates a new change set by comparing the record submitted to an existing record.  If an author is supplied, gives them credit, otherwise the current user is listed as the author.  Until a change set is approved by reviewers, only the author and reviewers can see the proposed changes.

+ Request (application/json}

    ```
    {
       "uniqueId": "existingRecord",
       "definition": "This existing record needs to be updated.",
       "notes": null
     }
    ```

+ Response 200 (application/json)
    + Body

        ```
        {
            "ok":true,
            "message":"Your proposed changes have been submitted.",
            "changeId": "0069b020043147f58eeda6d72c9845f4"
        }
        ```

## DELETE /api/record/{uniqueId}{?confirm}
Proposes that a record be flagged as trashed.  If an author is supplied, gives them credit, otherwise the current user is listed as the author.  Until a change set is approved by reviewers, only the author and reviewers can see the proposed changes, and the record will remain visible to end users.
Reviewers can confirm that a record should be flagged as deleted by sending the "confirm" parameter.

+ Parameters
    + uniqueId (required, string) ... The unique identifier of a single record.
    + confirm (required, string) ... Used to confirm that a proposed deletion should be executed.  Only available to reviewers.

+ Response 200 (application/json)

    ```
    {
        "ok": true,
        "message": "Record flagged for deletion."
    }
    ```

{'fraction_non_alphanumeric': 0.059263784939667025, 'fraction_numerical': 0.004887734840384909, 'mean_word_length': 4.019677996422183, 'pattern_counts': {'":': 30, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '3053524', 'n_tokens_mistral': 4721, 'n_tokens_neox': 4461, 'n_words': 2807}