<commit_before>@doc.main("api.json") {

  <h2>Schema declaration</h2>

  <p>
    A schema is represented in JSON as a JSON object of the form:

    <pre>
    {
      "name": <em>name</em>,
      "base_url": <em>string</em>,
      "models": <em>{ modelName: model, ... }</em>,
      "resources": <em>{ modelName: resource, ... }</em>,
      "description": <em>string (optional)</em>
    }
    </pre>

    where
    <ul>
      <li><em>name</em> specifies the human readable name of this service - used for display and as the basis for generating a unique key for URL</li>
      <li><em>baseUrl</em> specifies the base URL where this service is hosted. Must start with http.</li>
      <li><em>models</em> a JSON object defining all of the models in this API. The key of each object is the model name.</li>
      <li><em>resources</em> a JSON object defining all of the resources in this API. The key of each object is the name of the model that this resource represents. This name must be defined in the models object. </li>
      <li><em>description</em> optional description for what this service provides.</li>
    </ul>

  </p>

  <h2>Model declaration</h2>

  <p>
    A model is represented as a JSON object of the form:

    <pre>
    {
      "name" => {
        "description": <em>string (optional)</em>,
        "fields": <em>JSON Array of Field</em>
      }
    }
    </pre>

    where
    <ul>
      <li><em>name</em> the name of the model. Names must be alphanumeric and must start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters.</li>
      <li><em>description</em> optional longer description for what this model represents.</li>
      <li><em>fields</em> one or more fields is required. See <a href="#field">Fields</a>.</li>
    </ul>
  </p>

  <a name="field"></a>
  <h2>Field declaration</h2>

  <p>
    A field is represented as a JSON object of the form:

    <pre>
    {
      "name": <em>name</em>,
      "type": <em>type</em>,
      "description": <em>string (optional)</em>,
      "required": <em>boolean (optional, true by default)</em>,
      "enum": <em>JSON array of Strings (optional)</em>,
      "default": <em>type (optional)</em>,
      "example": <em>string (optional)</em>
    }
    </pre>

    where
    <ul>
      <li><em>name</em> the name of the field. Names must be alphanumeric and must start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters.</li>
      <li><em>type</em> the datatype of this field. This is an enumeration. Acceptable values are either the name of a model or the name of a primitive type (<a href="@routes.DocController.types">@core.Datatype.All.map(_.name).sorted.mkString(" ")</a>). To specify a collection, the type name can be wrapped with "[<name>]". For example, to specify that the type is a collection of strings, use "[string]".</li>
      <li><em>description</em> optional longer description for this field.</li>
      <li><em>required</em> boolean: true|false. By default all fields are considered required. To make a field optional, set "required" to false</li>
      <li><em>enum</em> Json Array of String values. This option can be used to define an enumeration - enum provides the list of all of the acceptable values for this field. There are a few constraints on enumerations. First, the datatype must be string. Second, the values themselves must be proper names. Valid characters are a-z, A-Z, 0-9 and _ characters.</li>
      <li><em>default</em> optional default value. Can only be used for primitive types. The value must be valid for the type specified for this field. For example, if you specify a field named 'limit' with type '@core.Datatype.IntegerType.name', an acceptable default would be 10</li>
      <li><em>example</em> optional - an example value for this field used only in the produced documentation</li>
    </ul>

  </p>

  <a name="resource"></a>
  <h2>Resource declaration</h2>

  <p>
    A resource is represented as a JSON object of the form:

    <pre>
    {
      "modelName" => {
        "path": <em>string (optional)</em>,
        "operations": <em>JSON Array of Operations</em>
      }
    }
    </pre>

    where
    <ul>
      <li><em>modelName</em> the name of the model that this resource represents</li>
      <li><em>path</em> optional path where this resource is located. If not provided, defaults to the model's plural name. Path parameters can be specified by prefixing a path element with ':'. For example, a path of '/:guid' would imply that all operations for this path will require a parameter named 'guid' of type 'string'</li>
      <li><em>operations</em> one or more operations is required. See <a href="#operation">Operation</a>.</li>
    </ul>
  </p>

  <a name="operation"></a>
  <h2>Operation declaration</h2>

  <p>
    An operation is represented as a JSON object of the form:

    <pre>
    {
      "method": <em>string</em>,
      "path": <em>string (optional)</em>,
      "description": <em>string (optional)</em>,
      "parameters": <em>JSON Array of Parameters</em>
      "responses": <em>JSON Object (optional)</em>
    }
    </pre>

    where
    <ul>
      <li><em>method</em> the HTTP method for this operation</li>
      <li><em>path</em> optional path for this particular operation. If not provided, defaults to no additional path. Path parameters can be specified by prefixing a path element with ':'. For example, a path of '/:guid' would imply that this operation is available at /resource_path/:guid. Path parameter types are inferred by looking for a field with that name on the model associated with this resource. If not found, the datatype of any path parameter will be string.</li>
      <li><em>description</em> optional longer description for this operation.</li>
      <li><em>parameters</em> optional JSON Array of the parameters to this method. See <a href="#parameter">Parameter</a>.</li>
      <li><em>responses</em> optional JSON Object of HTTP Response Code => Response. See <a name="#response"Response></a>. If not provided, an HTTP NoContent response is assumed. Only responses for HTTP status codes that are interesting should be documented.</li>
    </ul>
  </p>

  <a name="parameter"></a>
  <h2>Parameter declaration</h2>

  <p>
    A parameter is represented as a JSON object of the form:

    <pre>
    {
      "name": <em>name</em>,
      "type": <em>type</em>,
      "description": <em>string (optional)</em>,
      "required": <em>boolean (optional, true by default)</em>,
      "default": <em>type (optional)</em>,
      "example": <em>string (optional)</em>
    }
    </pre>

    where
    <ul>
      <li><em>name</em> the name of the parameter. Names must be alphanumeric and must start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters.</li>
      <li><em>type</em> the datatype of this parameter. This is an enumeration. Acceptable values are either the name of a model or the name of a primitive type (<a href="@routes.DocController.types">@core.Datatype.All.map(_.name).sorted.mkString(" ")</a>). To specify a collection, the type name can be wrapped with "[<name>]". For example, to specify that the type is a collection of strings, use "[string]".</li>
      <li><em>description</em> optional longer description for this parameter.</li>
      <li><em>required</em> boolean: true|false. By default all parameters are considered required. To make a parameter optional, set "required" to false</li>
      <li><em>default</em> optional default value. Can only be used for primitive types. The value must be valid for the type specified for this parameter. For example, if you specify a parameter named 'limit' with type '@core.Datatype.IntegerType.name', an acceptable default would be 10</li>
      <li><em>example</em> optional - an example value for this parameter used only in the produced documentation</li>
    </ul>

  </p>

  <a name="response"></a>
  <h2>Response declaration</h2>

  <p>
    A response is represented as a JSON object of the form:

    <pre>
    {
      "http_status_code": {
        "type": <em>type</em>
      }
    }
    </pre>

    where
    <ul>
      <li><em>http_status_code</em> A valid HTTP status code for this response (e.g. 200). Only status codes that have interesting return types should be documented.</li>
      <li><em>type</em> the datatype of this response. The value must be the name of a model. To specify a collection, the type name can be wrapped with "[<name>]". For example, to specify that the type is a collection of users (assuming there is a model with name user), use "[user]".</li>
    </ul>

  </p>


}<commit_msg>Update api.json schema with definition of bodies<commit_after>@doc.main("api.json") {

  <h2>Schema declaration</h2>

  <p>
    A schema is represented in JSON as a JSON object of the form:

    <pre>
    {
      "name": <em>name</em>,
      "base_url": <em>string</em>,
      "models": <em>{ modelName: model, ... }</em>,
      "resources": <em>{ modelName: resource, ... }</em>,
      "description": <em>string (optional)</em>
    }
    </pre>

    where
    <ul>
      <li><em>name</em> specifies the human readable name of this service - used for display and as the basis for generating a unique key for URL</li>
      <li><em>baseUrl</em> specifies the base URL where this service is hosted. Must start with http.</li>
      <li><em>models</em> a JSON object defining all of the models in this API. The key of each object is the model name.</li>
      <li><em>resources</em> a JSON object defining all of the resources in this API. The key of each object is the name of the model that this resource represents. This name must be defined in the models object. </li>
      <li><em>description</em> optional description for what this service provides.</li>
    </ul>

  </p>

  <h2>Model declaration</h2>

  <p>
    A model is represented as a JSON object of the form:

    <pre>
    {
      "name" => {
        "description": <em>string (optional)</em>,
        "fields": <em>JSON Array of Field</em>
      }
    }
    </pre>

    where
    <ul>
      <li><em>name</em> the name of the model. Names must be alphanumeric and must start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters.</li>
      <li><em>description</em> optional longer description for what this model represents.</li>
      <li><em>fields</em> one or more fields is required. See <a href="#field">Fields</a>.</li>
    </ul>
  </p>

  <a name="field"></a>
  <h2>Field declaration</h2>

  <p>
    A field is represented as a JSON object of the form:

    <pre>
    {
      "name": <em>name</em>,
      "type": <em>type</em>,
      "description": <em>string (optional)</em>,
      "required": <em>boolean (optional, true by default)</em>,
      "enum": <em>JSON array of Strings (optional)</em>,
      "default": <em>type (optional)</em>,
      "example": <em>string (optional)</em>
    }
    </pre>

    where
    <ul>
      <li><em>name</em> the name of the field. Names must be alphanumeric and must start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters.</li>
      <li><em>type</em> the datatype of this field. This is an enumeration. Acceptable values are either the name of a model or the name of a primitive type (<a href="@routes.DocController.types">@core.Datatype.All.map(_.name).sorted.mkString(" ")</a>). To specify a collection, the type name can be wrapped with "[<name>]". For example, to specify that the type is a collection of strings, use "[string]".</li>
      <li><em>description</em> optional longer description for this field.</li>
      <li><em>required</em> boolean: true|false. By default all fields are considered required. To make a field optional, set "required" to false</li>
      <li><em>enum</em> Json Array of String values. This option can be used to define an enumeration - enum provides the list of all of the acceptable values for this field. There are a few constraints on enumerations. First, the datatype must be string. Second, the values themselves must be proper names. Valid characters are a-z, A-Z, 0-9 and _ characters.</li>
      <li><em>default</em> optional default value. Can only be used for primitive types. The value must be valid for the type specified for this field. For example, if you specify a field named 'limit' with type '@core.Datatype.IntegerType.name', an acceptable default would be 10</li>
      <li><em>example</em> optional - an example value for this field used only in the produced documentation</li>
    </ul>

  </p>

  <a name="resource"></a>
  <h2>Resource declaration</h2>

  <p>
    A resource is represented as a JSON object of the form:

    <pre>
    {
      "modelName" => {
        "path": <em>string (optional)</em>,
        "operations": <em>JSON Array of Operations</em>
      }
    }
    </pre>

    where
    <ul>
      <li><em>modelName</em> the name of the model that this resource represents</li>
      <li><em>path</em> optional path where this resource is located. If not provided, defaults to the model's plural name. Path parameters can be specified by prefixing a path element with ':'. For example, a path of '/:guid' would imply that all operations for this path will require a parameter named 'guid' of type 'string'</li>
      <li><em>operations</em> one or more operations is required. See <a href="#operation">Operation</a>.</li>
    </ul>
  </p>

  <a name="operation"></a>
  <h2>Operation declaration</h2>

  <p>
    An operation is represented as a JSON object of the form:

    <pre>
    {
      "method": <em>string</em>,
      "path": <em>string (optional)</em>,
      "description": <em>string (optional)</em>,
      "body": <em>JSON Object (optional)</em>,
      "parameters": <em>JSON Array of Parameters (optional)</em>
      "responses": <em>JSON Object (optional)</em>
    }
    </pre>

    where
    <ul>
      <li><em>method</em> the HTTP method for this operation</li>
      <li><em>path</em> optional path for this particular operation. If not provided, defaults to no additional path. Path parameters can be specified by prefixing a path element with ':'. For example, a path of '/:guid' would imply that this operation is available at /resource_path/:guid. Path parameter types are inferred by looking for a field with that name on the model associated with this resource. If not found, the datatype of any path parameter will be string.</li>
      <li><em>description</em> optional longer description for this operation.</li>
      <li><em>body</em> optional specification for the type of the body of this request. For all operations that support bodies (e.g. POST, PUT, PATCH), allows you to specify the type of the body. See <a href="#body">Body</a>>.</li>
      <li><em>parameters</em> optional JSON Array of the parameters to this method. By default, for @core.Util.MethodsNotAcceptingBodies.mkString(" and ") methods, parameters are assumed to be in the path or in the query. For other methods, parameters are assumed to be in the path or form body, unless you have explicitly specified a body in which case parameters can be provided in the path or the query. See <a href="#parameter">Parameter</a>.</li>
      <li><em>responses</em> optional JSON Object of HTTP Response Code => Response. See <a name="#response"Response></a>. If not provided, an HTTP NoContent response is assumed. Only responses for HTTP status codes that are interesting should be documented.</li>
    </ul>
  </p>

  <a name="body"></a>
  <h2>Body declaration</h2>

  <p>
    A body is represented as a JSON object of the form:

    <pre>
    {
      "type": <em>type</em>
    }
    </pre>

    where
    <ul>
      <li><em>type</em> the name of a model describing this body.
    </ul>
  </p>

  <a name="parameter"></a>
  <h2>Parameter declaration</h2>

  <p>
    A parameter is represented as a JSON object of the form:

    <pre>
    {
      "name": <em>name</em>,
      "type": <em>type</em>,
      "description": <em>string (optional)</em>,
      "required": <em>boolean (optional, true by default)</em>,
      "default": <em>type (optional)</em>,
      "example": <em>string (optional)</em>
    }
    </pre>

    where
    <ul>
      <li><em>name</em> the name of the parameter. Names must be alphanumeric and must start with a letter. Valid characters are a-z, A-Z, 0-9 and _ characters.</li>
      <li><em>type</em> the datatype of this parameter. This is an enumeration. Acceptable values are either the name of a model or the name of a primitive type (<a href="@routes.DocController.types">@core.Datatype.All.map(_.name).sorted.mkString(" ")</a>). To specify a collection, the type name can be wrapped with "[<name>]". For example, to specify that the type is a collection of strings, use "[string]".</li>
      <li><em>description</em> optional longer description for this parameter.</li>
      <li><em>required</em> boolean: true|false. By default all parameters are considered required. To make a parameter optional, set "required" to false</li>
      <li><em>default</em> optional default value. Can only be used for primitive types. The value must be valid for the type specified for this parameter. For example, if you specify a parameter named 'limit' with type '@core.Datatype.IntegerType.name', an acceptable default would be 10</li>
      <li><em>example</em> optional - an example value for this parameter used only in the produced documentation</li>
    </ul>

  </p>

  <a name="response"></a>
  <h2>Response declaration</h2>

  <p>
    A response is represented as a JSON object of the form:

    <pre>
    {
      "http_status_code": {
        "type": <em>type</em>
      }
    }
    </pre>

    where
    <ul>
      <li><em>http_status_code</em> A valid HTTP status code for this response (e.g. 200). Only status codes that have interesting return types should be documented.</li>
      <li><em>type</em> the datatype of this response. The value must be the name of a model. To specify a collection, the type name can be wrapped with "[<name>]". For example, to specify that the type is a collection of users (assuming there is a model with name user), use "[user]".</li>
    </ul>

    There are a few conventions enforced:

    <ul>

      <li> HTTP Response codes of 404, 5xx cannot be explicitly
      specified and are handled automatically to ensure consistent
      behavior in generated client libraries.</li>

      <ul>

        <li> 404 response is automatically added for all GET requests</li>
        <li> if a successful response returns an array, 404 returns an empty list</li>
        <li> if a successful response returns a single instance, 404 returns null (or None in languages that support options)</li>

      </ul>

      <li> HTTP Response codes of 204 and 304 cannot contain a type - they must return no content.</li>

    </ul>


  </p>


}
{'fraction_non_alphanumeric': 0.12724853645556147, 'fraction_numerical': 0.004204364023416711, 'mean_word_length': 3.1692922121144886, 'pattern_counts': {'":': 60, '<': 562, '<?xml version=': 0, '>': 569, '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': '5547341', 'n_tokens_mistral': 5529, 'n_tokens_neox': 5376, 'n_words': 2324}