<commit_before>---
title: "Facility Service Definition Specification"
layout: page
---

# Facility Service Definition Specification

A Facility Service Definition (FSD) describes the operations supported by a Facility API.

## FSD File

A Facility Service Definition is typically represented by an FSD file, though [Open API (Swagger) 2.0](/docs/swagger) is also supported.

An FSD file uses a domain-specific language in an effort to make Facility Service Definitions easier to read and write, especially for developers comfortable with C-style languages.

Each FSD file contains the definition of one **service**. The name of an FSD file is typically the service name with an `.fsd` file extension, e.g. `MyApi.fsd`.

An FSD file should use UTF-8 with no byte order mark (BOM).

## Service

Every service has a **name**. Unless otherwise noted, a name in this specification must start with an ASCII letter but may otherwise contain ASCII letters, numbers, and/or underscores.

A service consists of **methods**, **data transfer objects**, **enumerated types**, and **error sets**. A service also supports **attributes**, a **summary**, and **remarks**.

#### FSD

In an FSD file, the `service` keyword starts the definition of a service. It is followed by the service name and optionally preceded by service attributes.

The methods and other service items follow the service name, enclosed in braces.

```
[http(url: "https://api.example.com/v1/")]
service MyApi
{
  method myMethod { ... }: { ... }
  data MyData { ... }
  enum MyEnum { ... }
  ...
}
```

#### HTTP

The `url` parameter of the `http` attribute indicates the base URL where the HTTP service lives. The trailing slash is optional. If the attribute or its parameter is omitted, the client will have to provide the base URL.

## Attributes

Attributes are used to attach additional information to a service and its elements.

Each attribute has an alphanumeric **name** and may optionally include one or more **parameters**. Each parameter has its own **name** as well as a **value**.

There is one standard attribute:

* `obsolete`: Indicates that the service element is obsolete and/or deprecated and should no longer be used.

#### FSD

In an FSD file, an attribute is surrounded by square brackets, and its optional parameters are comma-delimited and surrounded with parentheses.

Each parameter value can be represented as an ASCII token or a JSON-style double-quoted string. An ASCII token can consist of numbers, letters, periods, hyphens, plus signs, and/or underscores. An ASCII token is not semantically different than a double-quoted string containing that token.

```
[obsolete] // no parameters
[csharp(name: query)] // one parameter
[http(method: "GET", code: 202)] // two parameters
```

Multiple attributes can be comma-delimited within one set of square brackets and/or specified in separate sets of square brackets.

```
[obsolete, csharp(name: query)]
```

#### HTTP

Every Facility API has a default HTTP mapping. The HTTP mapping can be customized by using the `http` attribute, which can be applied to services, methods, request fields, response fields, and errors, as documented.

The `http` attribute is always optional. When the attribute is omitted, the defaults are used, as documented below.

## Methods

Each method represents an operation of the service.

Each method has a **name**, **request fields**, and **response fields**. A method also supports **attributes**, a **summary**, and **remarks**.

When a client invokes a service method, it provides values for some or all of the request fields. For example, a translation service could have a `translate` method with request fields named `text`, `sourceLanguage`, and `targetLanguage`.

If the method succeeds, values are returned for some or all of the response fields. A `translate` method might return the translated text in a `text` field and a confidence level in a `confidence` field.

If the method fails, a [service error](#service-errors) is returned instead.

#### FSD

In an FSD file, the `method` keyword starts the definition of a method. It is followed by the method name and optionally preceded by method attributes.

The request and response follow the method name, each enclosed in braces and separated by a colon (`:`). The request and response fields are listed within the braces.

```
  method translate
  {
    text: string;
    sourceLanguage: string;
    targetLanguage: string;
  }:
  {
    text: string;
    confidence: double;
  }
```

#### HTTP

The `http` attribute of a method supports a parameter named `method` that indicates the HTTP method that is used, e.g. `GET`, `POST`, `PUT`, `DELETE`, or `PATCH`. If omitted, the default is `POST`. Lowercase is permitted, e.g. `[http(method: get)]`.

The `path`  parameter indicates the HTTP path of the method (relative to the base URL). The path must start with a slash. A single slash indicates that the method is at the base URL itself.

For example, if a method uses `[http(method: GET, path: "/widgets"]` in a service that uses `[http(url: "https://api.example.com/v1/"]`, the full HTTP method and path for that method would be `GET https://api.example.com/v1/widgets`.

If the `path` parameter is not specified, it defaults to the method name, e.g. `/getWidgets` for a method named `getWidgets`. This default would not be appropriate for a RESTful API, but may be acceptable for an RPC-style API.

The `code` parameter indicates the HTTP status code used if the method is successful (but see also [body fields](#body-fields) below). If omitted, it defaults to `200` (OK), or to `204` (No Content) if the response has no relevant response fields.

```
  [http(method: POST, path: "/widgets", code: 201)]
  method createWidget
  {
    ...
  }:
  {
    ...
  }
```

## Fields

A field stores data for a method request, method response, or data transfer object.

Each field has a **name** and a **type**. The field type restricts the type of data that can be stored in that field.

Fields are generally optional, i.e. they may or may not store a value.

The following primitive field types are supported:

* `string`: A string of zero or more Unicode characters.
* `boolean`: A Boolean value, i.e. true or false.
* `double`: A double-precision floating-point number.
* `int32`: A 32-bit signed integer.
* `int64`: A 64-bit signed integer.
* `bytes`: Zero or more bytes.
* `object`: An arbitrary JSON object.
* `error`: A [service error](#service-errors).

A field type can be any data transfer object or enumerated type in the service, referenced by name.

A field type can be a service result. Use `result<T>` to indicate a service result; for example, `result<Widget>` is a service result whose value is a DTO named `Widget`.

A field type can be an array, i.e. zero or more ordered items of a particular type, including primitive types, data transfer objects, enumerated types, or service results. Use `T[]` to indicate an array; for example, `int32[]` is an array of `int32`.

A field type can be a dictionary that maps strings to values of a particular type, including primitive types, data transfer objects, enumerated types, or service results. Use `map<T>` to indicate a map; for example, `map<int32>` is a map of strings to `int32`.

Arrays or maps of other arrays or maps are not permitted.

#### FSD

In an FSD file, a field is represented by a name and a field type, which are separated by a colon (`:`) and followed by a semicolon (`;`). Fields can also be preceded by field attributes.

For fields whose type corresponds to a DTO or enumerated type, that DTO or enumerated type must be defined elsewhere in this service, before or after the method or DTO that contains the field.

#### JSON

Since [JSON](http://www.json.org/) is currently the most commonly-used serialization format for APIs over HTTP, Facility APIs are designed to be trivially compatible with JSON.

In a JSON request body, response body, or DTO, a field is serialized as a JSON object property. In fact, to avoid complicating implementations, there is no way to customize the JSON serialization of a request body, response body, or DTO. Each field is always serialized as a JSON property with the same name.

* `string`, `boolean`, `double`, `int32`, and `int64` are encoded as JSON literals.
* `bytes` are encoded as a [Base64](https://en.wikipedia.org/wiki/Base64) string.
* `object` is encoded as a JSON object.
* `error` is encoded as a JSON object with `code`, `message`, `details`, and `innerError` properties.
* `result<T>` is encoded as a JSON object with a `value` or `error` property.
* `T[]` is encoded as a JSON array.
* `map<T>` is encoded as a JSON object.

`null` is not a valid value for any field type. If a JSON property is set to `null`, it is treated as though it were omitted. Arrays and maps are not permitted to have `null` items.

When reading JSON, conforming clients and servers may match property names case-insensitively, and they may perform type conversions for property values, e.g. strings to numbers. They may also support non-standard JSON features, such as unquoted property names, single-quoted strings, comments, etc.

However, when writing JSON, conforming clients and servers must always use [standard JSON](http://www.json.org/) with no comments, correctly-cased property names, correctly-typed property values, etc.

#### HTTP

On a request or response field, the `from` parameter of the `http` attribute indicates where the field comes from. It can be set to `path`, `query`, `body`, `header`, or `normal`. Like all `http` parameters, the `from` parameter is optional; see below for defaults.

The `http` attribute should not be used on a DTO field.

#### Path Fields<commit_msg>More spec changes.<commit_after>---
title: "Facility Service Definition Specification"
layout: page
---

# Facility Service Definition Specification

A Facility Service Definition (FSD) describes the operations supported by a Facility API.

Unlike other API definition formats, an FSD focuses on the shape of the client library rather than on the HTTP paths. Each service operation has a name, request fields, and response fields. In that way it resembles [RPC](https://en.wikipedia.org/wiki/Remote_procedure_call) more than [REST](https://en.wikipedia.org/wiki/Representational_state_transfer), though it can certainly be used to describe RESTful APIs.

## FSD File

A Facility Service Definition is typically represented by an FSD file, though [Open API (Swagger) 2.0](/docs/swagger) is also supported.

An FSD file uses a domain-specific language in an effort to make Facility Service Definitions easier to read and write, especially for developers comfortable with C-style languages.

Each FSD file contains the definition of one **service**. The name of an FSD file is typically the service name with an `.fsd` file extension, e.g. `MyApi.fsd`.

An FSD file is a text file encoded with UTF-8 and no byte order mark (BOM).

## Service

Every service has a **name**. Unless otherwise noted, a name in this specification must start with an ASCII letter but may otherwise contain ASCII letters, numbers, and/or underscores.

A service consists of **methods**, **data transfer objects**, **enumerated types**, and **error sets**. A service also supports **attributes**, a **summary**, and **remarks**.

#### FSD

In an FSD file, the `service` keyword starts the definition of a service. It is followed by the service name and optionally preceded by service attributes.

The methods and other service items follow the service name, enclosed in braces.

```
[http(url: "https://api.example.com/v1/")]
service MyApi
{
  method myMethod { ... }: { ... }
  data MyData { ... }
  enum MyEnum { ... }
  ...
}
```

#### HTTP

The `url` parameter of the `http` attribute indicates the base URL where the HTTP service lives. The trailing slash is optional. If the attribute or its parameter is omitted, the client will have to provide the base URL.

## Attributes

Attributes are used to attach additional information to a service and its elements.

Each attribute has an alphanumeric **name** and may optionally include one or more **parameters**. Each parameter has its own **name** as well as a **value**.

The `obsolete` attribute indicates that the service element is obsolete and/or deprecated and should no longer be used. It has no parameters.

#### FSD

In an FSD file, the attribute name is surrounded by square brackets. The comma-delimited parameters, if any, are surrounded by parentheses and follow the attribute name.

Each parameter value can be represented as an ASCII token or a [JSON-style](http://www.json.org/) double-quoted string. An ASCII token can consist of numbers, letters, periods, hyphens, plus signs, and/or underscores. An ASCII token is not semantically different than a double-quoted string containing that token.

```
[obsolete] // no parameters
[csharp(name: query)] // one parameter
[http(path: "/search", code: 202)] // two parameters
```

Multiple attributes can be comma-delimited within one set of square brackets (as below) and/or specified in separate sets of square brackets (as above).

```
[obsolete, csharp(name: query)]
```

#### HTTP

Every Facility API has a default HTTP mapping. The HTTP mapping can be customized by using the `http` attribute, which can be applied to services, methods, request fields, response fields, and errors.

The `http` attribute is always optional. When the attribute is omitted, the defaults are used, as documented.

## Methods

Each method represents an operation of the service.

A method has a **name**, **request fields**, and **response fields**. A method also supports **attributes**, a **summary**, and **remarks**.

When a client invokes a service method, it provides values for some or all of the request fields. For example, a translation service could have a `translate` method with request fields named `text`, `sourceLanguage`, and `targetLanguage`.

If the method succeeds, values are returned for some or all of the response fields. A `translate` method might return the translated text in a `text` field and a confidence level in a `confidence` field.

If the method fails, a [service error](#service-errors) is returned instead.

#### FSD

In an FSD file, the `method` keyword starts the definition of a method. It is followed by the method name and optionally preceded by method attributes.

The request and response follow the method name, each enclosed in braces and separated by a colon (`:`). The request and response fields, if any, are listed within the braces.

```
  method translate
  {
    text: string;
    sourceLanguage: string;
    targetLanguage: string;
  }:
  {
    text: string;
    confidence: double;
  }
```

#### HTTP

The `http` attribute of a method supports a parameter named `method` that indicates the HTTP method that is used, e.g. `GET`, `POST`, `PUT`, `DELETE`, or `PATCH`. If omitted, the default is `POST`. Lowercase is permitted, e.g. `[http(method: get)]`.

The `path`  parameter indicates the HTTP path of the method (relative to the base URL). The path must start with a slash. A single slash indicates that the method is at the base URL itself.

For example, if a method uses `[http(method: GET, path: "/widgets"]` in a service that uses `[http(url: "https://api.example.com/v1/"]`, the full HTTP method and path for that method would be `GET https://api.example.com/v1/widgets`.

If the `path` parameter is not specified, it defaults to the method name, e.g. `/getWidgets` for a method named `getWidgets`. This default would not be appropriate for a RESTful API, but may be acceptable for an RPC-style API.

The `code` parameter indicates the HTTP status code used if the method is successful (but see also [body fields](#body-fields) below). If omitted, it defaults to `200` (OK), or to `204` (No Content) if the response has no relevant response fields.

```
  [http(method: POST, path: "/widgets", code: 201)]
  method createWidget
  {
    ...
  }:
  {
    ...
  }
```

## Fields

A field stores data for a method request, method response, or data transfer object.

Each field has a **name** and a **type**. The field type restricts the type of data that can be stored in that field.

Fields are generally optional, i.e. they may or may not store a value.

The following primitive field types are supported:

* `string`: A string of zero or more Unicode characters.
* `boolean`: A Boolean value, i.e. true or false.
* `double`: A double-precision floating-point number.
* `int32`: A 32-bit signed integer.
* `int64`: A 64-bit signed integer.
* `bytes`: Zero or more bytes.
* `object`: An arbitrary JSON object.
* `error`: A [service error](#service-errors).

A field type can be any [data transfer object](#data-transfer-objects) or [enumerated type](#enumerated-types) in the service, referenced by name.

A field type can be a [service result](#service-results). Use `result<T>` to indicate a service result; for example, `result<Widget>` is a service result whose value is a DTO named `Widget`.

A field type can be an array, i.e. zero or more ordered items of a particular type, including primitive types, data transfer objects, enumerated types, or service results. Use `T[]` to indicate an array; for example, `int32[]` is an array of `int32`.

A field type can be a dictionary that maps strings to values of a particular type, including primitive types, data transfer objects, enumerated types, or service results. Use `map<T>` to indicate a map; for example, `map<int32>` is a map of strings to `int32`.

Arrays or maps of other arrays or maps are not permitted.

#### FSD

In an FSD file, a field is represented by a name and a field type, which are separated by a colon (`:`) and followed by a semicolon (`;`). Fields can also be preceded by field attributes.

For fields whose type corresponds to a DTO or enumerated type, that DTO or enumerated type must be defined elsewhere in this service, before or after the method or DTO that contains the field.

#### JSON

Since [JSON](http://www.json.org/) is currently the most commonly-used serialization format for APIs over HTTP, Facility APIs are designed to be trivially compatible with JSON.

In a JSON request body, response body, or DTO, a field is serialized as a JSON object property. In fact, to avoid complicating implementations, there is no way to customize the JSON serialization of a request body, response body, or DTO. Each field is always serialized as a JSON property with the same name.

* `string`, `boolean`, `double`, `int32`, and `int64` are encoded as JSON literals.
* `bytes` are encoded as a [Base64](https://en.wikipedia.org/wiki/Base64) string.
* `object` is encoded as a JSON object.
* `error` is encoded as a JSON object with `code`, `message`, `details`, and `innerError` properties.
* `result<T>` is encoded as a JSON object with a `value` or `error` property.
* `T[]` is encoded as a JSON array.
* `map<T>` is encoded as a JSON object.

`null` is not a valid value for any field type. If a JSON property is set to `null`, it is treated as though it were omitted. Arrays and maps are not permitted to have `null` items.

Even though `int64` is a 64-bit signed integer, avoid ±2<sup>51</sup> or larger, as JavaScript [cannot safely represent](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER) integers that large.

When reading JSON, conforming clients and servers may match property names case-insensitively, and they may perform type conversions for property values, e.g. strings to numbers. They may also support non-standard JSON features, such as unquoted property names, single-quoted strings, comments, etc.

However, when writing JSON, conforming clients and servers must always use [standard JSON](http://www.json.org/) with no comments, correctly-cased property names, correctly-typed property values, etc.

#### HTTP

On a request or response field, the `from` parameter of the `http` attribute indicates where the field comes from. It can be set to `path`, `query`, `body`, `header`, or `normal`. Like all `http` parameters, the `from` parameter is optional; see below for defaults.

The `http` attribute should not be used on a DTO field.

#### Path Fields
{'fraction_non_alphanumeric': 0.08991368680641183, 'fraction_numerical': 0.004488286066584464, 'mean_word_length': 4.254210935475512, 'pattern_counts': {'":': 0, '<': 17, '<?xml version=': 0, '>': 17, 'https://': 11, 'lorem ipsum': 0, 'www.': 5, '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': '5578264', 'n_tokens_mistral': 5487, 'n_tokens_neox': 5196, 'n_words': 2980}