<commit_before>Specification
=============

**Current Version**: |version|

**Current Release**: |release|

**Build Date**: |today|

**Proposed Registration**: ``application/vnd.verbose+json``

The document outlines the Verbose hypermedia format.

.. note ::
  This is currently in active development. There may be parts of this change before it is ready for use.

.. note ::
  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
  NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
  "OPTIONAL" in this document are to be interpreted as described in
  RFC 2119.

.. _definitions:

Definitions
-----------

Since Verbose reuses a lot of properites, this section will first define some of these common properties. 

Identifying
###########

These properties define identifying information for items throughout a document.

``id``
  A unique identifier for an item. It MUST be unique for the entire document. It is a ``string``.

``name``
  A way to give a name to an item in the Verbose document. It is a ``string``.

``label``
  Human-readable label for a property

``title``
  A human-readable title for an item. It is a ``string``.

``description``
  A human-readable description for an item. It is a ``string``.

Hypermedia
##########

These properties are used to define hypermedia information and hints related to links, queries, actions, and resources.

``embedAs``
  A way to tell the client how an item should be embedded. These are the possible values:

  1. image
  2. audio
  3. video
  4. text
  5. application

  If left blank, it is assumed to be a normal link.

``rels``
  An ``array`` of link relations for an item.

``responseTypes``
  An ``array`` of available media types on the server.

Types
#####

``typesOf``
  A way to specify what type of item an item is. Useful when specifying Schema.org values or linking to profiles. It is an array of strings. If multiple types are specified, the first type is of most priority and the last type is of least, in the event that there are conflicting restraints. Having several types is an option, but it may be better to create and define a new type if there are too many.

  By default, Verbose supports the JSON primitives:

  1. string
  2. number
  3. boolean
  4. array
  5. object

  You can of course create your own types and define certain constraints and validations on the object. See the 

Extensibility
#############

Each of these properties use :ref:`Verbose Path <verbose_path>` to reference items from the same document or other documents. Please see the documentation on this to understand how Verbose Path works.

``extend``
  A way to extend the item with other items. It is an object, the contents of which can be defined outside of this spec.

``forEach``
  An ``array`` of Verbose Paths that specify for what item a template can be used. These templates can be for links, queries, actions, or resource templates.

  If the Verbose Path string specified references more than one item in the document, it means that template can be used for each of those items.

  ::

    {
      "verbose": {
        "href": "/customers",
        "templates": [
          {
            "forEach": [ "#", "#/includes[rel=item]" ]
          }
        ]
      }
    }

  In this example above, the ``forEach`` array contains a reference to ``#``, which references the root resource of the document, and ``#/includes[rel=item]``, which references any included items with a link relation of ``item``. Please see the Verbose Path section to see how it is used. 

``mapsTo``
  An ``array`` of Verbose Path strings (see  section for details on how this is used)

.. _namespace:

Namespace
---------

All Verbose documents MUST have a ``verbose`` namespace.

::

  {
    "verbose": {}
  }

.. _prefixes:

Prefixes
--------

Prefixes can be used to shorten URLs. When used, they are available throughout the entire document.

``prefixes``
  This is an ``array`` of prefix objects.

  ``prefix``
    The short prefix name.

  ``href``
    The URL to be used as the prefix.

Example
#######

::

  {
    "verbose": {
      "version": "0.4",
      "prefixes": [
        {
          "prefix": "schema",
          "href": "http://schema.org/"
        }
      ]
    }
  }

.. _properties:

Properties
----------

The ``properties`` object is simply a JSON object. Its semantics are defined by the Semantic object.

.. _semantics:

Semantics
---------

The ``semantics`` array is an array of Semantic objects. It supports the following properites listed in the :ref:`Definitions <definitions>` list:

1. ``id`` - Unique identifier for semantic
2. ``name`` - Name of property being defined
3. ``type`` - Type of the property
4. ``format`` - HTML format of the property
5. ``typesOf`` - For pointing to another semantic or schema for the property
6. ``mapsTo`` - Property to which the semantic point

Example
#######

Below is an example showing a resource that has ``properties`` and ``semantics`` for those properties. In this example, the property is ``email``, which is a ``string`` and uses the HTML5 formatting for ``email``. The instance data for that property is ``<EMAIL>``.

::

  {
    "verbose": {
      "semantics": [
        {
          "name": "email",
          "type": "string",
          "format": "email",
          "label": "Email",
          "mapsTo": "#/properties.email"
        }
      ],
      "properties": {
        "email": "<EMAIL>"
      }
    }
  }

.. _field:

Field
-----

A Field object supports the following properites listed in the :ref:`Definitions <definitions>` list:

1. ``id`` - Unique identifier for field
2. ``name`` - Name of field
3. ``typesOf`` - Types of the field
4. ``extend`` - Added details determined by the type

A ``field`` object also provides the following properties:

``defaultValue``
  The optional default value of the field. This is a ``string``.

``currentValue``
  The current value of the field. This is a ``string``.

``value``
  The value of the field which cannot be changed. The ``defaultValue`` and ``currentValue`` properties allow for the values to be changed or set, though the ``value`` property is unchangeable. It is a way for the API to provide unchangeable field data, equivalent to a hidden field in HTML.

``options``
  An ``array`` of option objects. Option objects have a ``name`` and ``value`` property for each option.

.. _transitions:

Transitions
-----------

A transition is a way in which a client can interact with this resource or other related resources. It can be seen as a link to a resource or even an action that can be taken, such as updating a resource.

The ``transitions`` property is an array of Transition objects. It supports the following properites listed in the :ref:`Definitions <definitions>` list:

1. ``id`` - Unique identifier for item
2. ``name`` - Name of transition
3. ``rels`` - Link relation of the transition
4. ``responseTypes`` - Types with which the server may respond
5. ``requestTypes`` - Types in which the server accepts
6. ``embedAs`` - Ways to inform the client how an item should be transcluded
7. ``href`` - URL for the transition
8. ``hreft`` - URL template
9. ``mapsTo`` - An array of Verbose Paths to map a transition to another property
10. ``typesOf`` - For pointing to another semantic or schema for the transition
11. ``method`` - For specifying the protocol method to use with the transition. If this is not set, GET SHOULD be assumed.

The ``href`` and ``hreft`` properties MUST NOT be used together in the same transition. The different is that the ``hreft`` property is a URI template that requires different processing.

An transition can have different types of parameters that can be used at different times.

``bodyParams``
  An ``array`` of ``field`` objects that is used for specifying the parameters for the body of a request  

``uriParams``
  An ``array`` of ``field`` objects that is used for specifying the parameters for a URI template or for query parameters. When used with a transition containing an ``href``, it should be used as query parameters. When used with a transition with ``hreft``, it should be used as URI template parameters.

  When used with a templated transition that uses ``hreft``, all URL path parameters MUST be required, even if not explicitly stated.

Link Example
############

The transition below provides a link to a customer resource.<commit_msg>Clarify properties for semantics, fields, and transitions<commit_after>Specification
=============

**Current Version**: |version|

**Current Release**: |release|

**Build Date**: |today|

**Proposed Registration**: ``application/vnd.verbose+json``

The document outlines the Verbose hypermedia format.

.. note ::
  This is currently in active development. There may be parts of this change before it is ready for use.

.. note ::
  The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
  NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and
  "OPTIONAL" in this document are to be interpreted as described in
  RFC 2119.

.. _definitions:

Definitions
-----------

Since Verbose reuses a lot of properites, this section will first define some of these common properties. 

Identifying
###########

These properties define identifying information for items throughout a document.

``id``
  A unique identifier for an item. It MUST be unique for the entire document. It is a ``string``.

``name``
  A way to give a name to an item in the Verbose document. It is a ``string``.

``label``
  Human-readable label for a property

``title``
  A human-readable title for an item. It is a ``string``.

``description``
  A human-readable description for an item. It is a ``string``.

Hypermedia
##########

These properties are used to define hypermedia information and hints related to links, queries, actions, and resources.

``embedAs``
  A way to tell the client how an item should be embedded. These are the possible values:

  1. image
  2. audio
  3. video
  4. text
  5. application

  If left blank, it is assumed to be a normal link.

``rels``
  An ``array`` of link relations for an item.

``responseTypes``
  An ``array`` of available media types on the server.

Types
#####

``typesOf``
  A way to specify what type of item an item is. Useful when specifying Schema.org values or linking to profiles. It is an array of strings. If multiple types are specified, the first type is of most priority and the last type is of least, in the event that there are conflicting restraints. Having several types is an option, but it may be better to create and define a new type if there are too many.

  By default, Verbose supports the JSON primitives:

  1. string
  2. number
  3. boolean
  4. array
  5. object

  You can of course create your own types and define certain constraints and validations on the object. See the 

Extensibility
#############

Each of these properties use :ref:`Verbose Path <verbose_path>` to reference items from the same document or other documents. Please see the documentation on this to understand how Verbose Path works.

``extend``
  A way to extend the item with other items. It is an object, the contents of which can be defined outside of this spec.

``forEach``
  An ``array`` of Verbose Paths that specify for what item a template can be used. These templates can be for links, queries, actions, or resource templates.

  If the Verbose Path string specified references more than one item in the document, it means that template can be used for each of those items.

  ::

    {
      "verbose": {
        "href": "/customers",
        "templates": [
          {
            "forEach": [ "#", "#/includes[rel=item]" ]
          }
        ]
      }
    }

  In this example above, the ``forEach`` array contains a reference to ``#``, which references the root resource of the document, and ``#/includes[rel=item]``, which references any included items with a link relation of ``item``. Please see the Verbose Path section to see how it is used. 

``mapsTo``
  An ``array`` of Verbose Path strings (see  section for details on how this is used)

.. _namespace:

Namespace
---------

All Verbose documents MUST have a ``verbose`` namespace.

::

  {
    "verbose": {}
  }

.. _prefixes:

Prefixes
--------

Prefixes can be used to shorten URLs. When used, they are available throughout the entire document.

``prefixes``
  This is an ``array`` of prefix objects.

  ``prefix``
    The short prefix name.

  ``href``
    The URL to be used as the prefix.

Example
#######

::

  {
    "verbose": {
      "version": "0.4",
      "prefixes": [
        {
          "prefix": "schema",
          "href": "http://schema.org/"
        }
      ]
    }
  }

.. _properties:

Properties
----------

The ``properties`` object is simply a JSON object. Its semantics are defined by the Semantic object.

.. _semantics:

Semantics
---------

The ``semantics`` array is an array of Semantic objects. It supports the following properites listed in the :ref:`Definitions <definitions>` list:

1. ``id`` - Unique identifier for semantic
2. ``name`` - Name of property being defined
3. ``title`` - Title of semantic
4. ``description`` - Description of semantic
5. ``label`` - Human-readable label or prompt for semantic
6. ``type`` - Type of the property
7. ``format`` - HTML format of the property
8. ``typesOf`` - For pointing to another semantic or schema for the property
9. ``mapsTo`` - Property to which the semantic point

Example
#######

Below is an example showing a resource that has ``properties`` and ``semantics`` for those properties. In this example, the property is ``email``, which is a ``string`` and uses the HTML5 formatting for ``email``. The instance data for that property is ``<EMAIL>``.

::

  {
    "verbose": {
      "semantics": [
        {
          "name": "email",
          "type": "string",
          "format": "email",
          "label": "Email",
          "mapsTo": "#/properties.email"
        }
      ],
      "properties": {
        "email": "<EMAIL>"
      }
    }
  }

.. _field:

Field
-----

A Field object supports the following properites listed in the :ref:`Definitions <definitions>` list:

1. ``id`` - Unique identifier for field
2. ``name`` - Name of field
3. ``title`` - Title of field
4. ``description`` - Description of field
5. ``label`` - Human-readable label or prompt for field
6. ``typesOf`` - Types of the field
7. ``extend`` - Added details determined by the type

A ``field`` object also provides the following properties:

``defaultValue``
  The optional default value of the field. This is a ``string``.

``currentValue``
  The current value of the field. This is a ``string``.

``value``
  The value of the field which cannot be changed. The ``defaultValue`` and ``currentValue`` properties allow for the values to be changed or set, though the ``value`` property is unchangeable. It is a way for the API to provide unchangeable field data, equivalent to a hidden field in HTML.

``options``
  An ``array`` of option objects. Option objects have a ``name`` and ``value`` property for each option.

.. _transitions:

Transitions
-----------

A transition is a way in which a client can interact with this resource or other related resources. It can be seen as a link to a resource or even an action that can be taken, such as updating a resource.

The ``transitions`` property is an array of Transition objects. It supports the following properites listed in the :ref:`Definitions <definitions>` list:

1. ``id`` - Unique identifier for item
2. ``name`` - Name of transition
3. ``title`` - Title of transition
4. ``description`` - Description of transition
5. ``label`` - Human-readable label or prompt for transition
6. ``rels`` - Link relation of the transition
7. ``responseTypes`` - Types with which the server may respond
8. ``requestTypes`` - Types in which the server accepts
9. ``embedAs`` - Ways to inform the client how an item should be transcluded
10. ``href`` - URL for the transition
11. ``hreft`` - URL template
12. ``mapsTo`` - An array of Verbose Paths to map a transition to another property
13. ``typesOf`` - For pointing to another semantic or schema for the transition
14. ``method`` - For specifying the protocol method to use with the transition. If this is not set, GET SHOULD be assumed.

The ``href`` and ``hreft`` properties MUST NOT be used together in the same transition. The different is that the ``hreft`` property is a URI template that requires different processing.

An transition can have different types of parameters that can be used at different times.

``bodyParams``
  An ``array`` of ``field`` objects that is used for specifying the parameters for the body of a request  

``uriParams``
  An ``array`` of ``field`` objects that is used for specifying the parameters for a URI template or for query parameters. When used with a transition containing an ``href``, it should be used as query parameters. When used with a transition with ``hreft``, it should be used as URI template parameters.

  When used with a templated transition that uses ``hreft``, all URL path parameters MUST be required, even if not explicitly stated.

Link Example
############

The transition below provides a link to a customer resource.
{'fraction_non_alphanumeric': 0.10933240531291688, 'fraction_numerical': 0.005336117394582681, 'mean_word_length': 3.3617505691879583, 'pattern_counts': {'":': 38, '<': 15, '<?xml version=': 0, '>': 15, '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': '2844945', 'n_tokens_mistral': 4720, 'n_tokens_neox': 4554, 'n_words': 2431}