OpenAPI 3.0 Standards Compliance

Supported Components

The following components are not supported:

  • examples
  • securitySchemes
  • links
  • callbacks

Supported Data Types

null is not a type in OpenAPI, but it is a type in JSON Schema. Since OaDocument (theoretically) should support both, null is allowed as a data type.

Confer: * https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#data-types * https://json-schema.org/understanding-json-schema/reference/null

Supported Content Types

Only JSON is supported. XML is not supported.

Schema Fields

  • The readOnly and writeOnly field are ignored.
  • The discriminator field is ignored.
  • The externalDocs field is ignored.

Built-in Formats

The format property can influence all data types except the following: * unit. If you need different flavors of a zero-dimension value, use null. There are data formats like Ion where the flavor of null is important.

As of this version of OaDocument only the following formats are supported:

  • "date-time" which is represented as a Ptime.t
  • "time" which is represented as a Ptime.time
  • "duration" which is represented as a Ptime.date

Other formats are supported in "vendor" extensions.

Supported Vendor Extensions

  • StripeExt supports the "unix-time" epoch second time format

Abstract representation of OpenAPI documents

Sourcetype param_in = OaTypes.param_in =
  1. | Query
  2. | Header
  3. | Path
  4. | Cookie
Sourcetype param_style = OaTypes.param_style =
  1. | Matrix
  2. | Label
  3. | Form
  4. | Simple
  5. | SpaceDelimited
  6. | PipeDelimited
  7. | DeepObject
Sourcetype pathobj_seg = OaTypes.pathobj_seg =
  1. | PathLiteralPart of string
  2. | PathFieldPart of string
Sourcetype operation_id = OaTypes.operation_id =
  1. | OpPath of {
    1. doc_path : Json_query.path;
    2. path_template : string;
    3. name : string;
    }
    (*

    OpPath {doc_path;path_template;name} is the operation identifier when the id = field "operationId" is not specified, causing the document path doc_path to become the unique identifier.

    *)
  2. | OpId of {
    1. id : string;
    2. path_template : string;
    3. name : string;
    }
    (*

    OpId {id;path_template;name} is the operation identifier when the id = field "operationId" is specified.

    *)

The type of unique identifier for an operation.

Each operation identifier has a path_template like "/v1/accounts/{accountId}" and an operation name like "get".

Sourcetype param_ref = OaTypes.param_ref = {
  1. param_name : string;
    (*

    The name of the parameter. Parameter names are case sensitive. If in is "path", the name field MUST correspond to the associated path segment from the path field in the Paths Object. See Path Templating for further information. If in is "header" and the name field is "Accept", "Content-Type" or "Authorization", the parameter definition SHALL be ignored. For all other cases, the name corresponds to the parameter name used by the in property.

    *)
  2. param_in : param_in;
    (*

    The location of the parameter. Possible values are "query", "header", "path" or "cookie".

    *)
}

The fields that make a unique parameter.

Confer: https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#parameter-object > A unique parameter is defined by a combination of a name and location.

Name is the parameter name field and location is the parameter in field.

The uniqueness is relative to an operation.

Sourcetype response_code = OaTypes.response_code =
  1. | Explicit_code of int
    (*

    Explicit_code 200 is the HTTP 200 status code.

    *)
  2. | Hundreds_code of int
    (*

    Hundreds_code 2 is the range 200-299 of status codes.

    *)

The type of a OpenAPI specification document.

Conventionally the document is named "openapi.json" or "openapi.yaml".

Sourcetype t
Sourcetype schema = OaTypes.schema = {
  1. title : string option;
    (*

    An optional short description.

    *)
  2. description : string option;
    (*

    An optional long description.

    *)
  3. default : Json_repr.any option;
    (*

    A default constant to be substituted in case of a missing value.

    *)
  4. enum : Json_repr.any list option;
    (*

    A valid value must equal one of these constants.

    *)
  5. kind : schema_kind;
    (*

    The type-specific part.

    *)
  6. format : string option;
    (*

    predefined formats such as date-time, email, ipv4, ipv6, uri.

    *)
  7. id : string option;
    (*

    An optional ID.

    In JSON Schema multiple schemas can be bundled into a single schema using the $id (or id in Draft 4 or later) field. Confer with JSON Schema Bundling.

    *)
  8. schema_ref : Json_query.path;
    (*

    schema_ref is the location of the schema in the document.

    *)
}

A Schema object.

All fields except kind are type-agnostic specifications.

Sourceand schema_kind = OaTypes.schema_kind =
  1. | Object of object_specs
    (*

    The type of an object.

    *)
  2. | Array of schema list * array_specs
    (*

    An fixed-length array with the types of its elements (a tuple).

    *)
  3. | Monomorphic_array of schema * array_specs
    (*

    A variable-length array with the type of its children.

    *)
  4. | Combine of combinator * schema list
    (*

    A mix of schemas using logical combinators.

    *)
  5. | Schema_ref of Json_query.path
    (*

    A ref to an element from its path in the JSON representation.

    *)
  6. | Id_ref of string
    (*

    A ref to an element from its ID.

    *)
  7. | Ext_ref of Restapis_o.Open__.Uri.t
    (*

    A ref to an external element.

    *)
  8. | String of string_specs
    (*

    A string (with optional characteristics).

    *)
  9. | Integer of numeric_specs
    (*

    An int (with optional characteristics).

    *)
  10. | Number of numeric_specs
    (*

    A float (with optional characteristics).

    *)
  11. | Boolean
    (*

    Any boolean.

    *)
  12. | Null
    (*

    The null value.

    *)
  13. | Any
    (*

    Any JSON value.

    *)
  14. | Dummy
    (*

    For building cyclic definitions, a component bound to a dummy will be considered absent for add_schema but present for update. The idea is to insert a dummy component, build a cyclic structure using it for recursion, and finally update the component with the structure.

    *)

The type-specific part of schema nodes.

Sourceand combinator = OaTypes.combinator =
  1. | Any_of
    (*

    Logical OR n-ary combinator.

    *)
  2. | One_of
    (*

    Logical XOR n-ary combinator.

    *)
  3. | All_of
    (*

    Logical AND n-ary combinator.

    *)
  4. | Not
    (*

    Logical NOT unary combinator.

    *)

Grammar combinators.

Sourceand array_specs = OaTypes.array_specs = {
  1. min_items : int;
    (*

    The minimum number of elements.

    *)
  2. max_items : int option;
    (*

    The maximum number of elements.

    *)
  3. unique_items : bool;
    (*

    Teels if all elements must be different.

    *)
  4. additional_items : schema option;
    (*

    The type of additional items, if allowed.

    *)
}

Parameters of the Array and MonomorphicArray type specifiers.

Sourceand numeric_specs = OaTypes.numeric_specs = {
  1. multiple_of : float option;
    (*

    An optional divisor of valid values

    *)
  2. minimum : (float * [ `Inclusive | `Exclusive ]) option;
    (*

    The optional lower bound of the numeric range

    *)
  3. maximum : (float * [ `Inclusive | `Exclusive ]) option;
    (*

    The optional upper bound of the numeric range

    *)
}

Parameters of the Integer and Number type specifiers.

Sourceand object_specs = OaTypes.object_specs = {
  1. properties : object_props list;
    (*

    The names and types of properties, with a flag to indicate if they are required (true) or optional.

    *)
  2. pattern_properties : (string * schema) list;
    (*

    Alternative definition of properties, matching field names using regexps instead of constant strings.

    *)
  3. additional_properties : schema option;
    (*

    The type of additional properties, if allowed.

    *)
  4. min_properties : int;
    (*

    The minimum number of properties.

    *)
  5. max_properties : int option;
    (*

    The maximum number of properties.

    *)
  6. schema_dependencies : (string * schema) list;
    (*

    Additional schemas the value must verify if a property is present (property, additional schema).

    *)
  7. property_dependencies : (string * string list) list;
    (*

    Additional properties required whenever some property is present (property, additional properties).

    *)
}

Parameters of the Object type specifier.

Sourceand string_specs = OaTypes.string_specs = {
  1. pattern : string option;
    (*

    A regexp the string must conform to.

    *)
  2. min_length : int;
    (*

    The minimum string length.

    *)
  3. max_length : int option;
    (*

    The maximum string length.

    *)
  4. str_format : string option;
    (*

    Special format of the string (cf json schema documentation).

    *)
}

Parameters of the String type specifier.

Sourceand object_props = OaTypes.object_props = {
  1. prop_name : string;
  2. prop_type : schema;
  3. required : bool;
    (*

    Whether the property is required or not.

    *)
  4. nullable : bool;
    (*

    Allows sending a null value for the defined schema. Default value is false.

    *)
  5. read_only : bool;
    (*

    Declares the property as "read only". This means that it MAY be sent as part of a response but SHOULD NOT be sent as part of the request. If the property is marked as readOnly being true and is in the required list, the required will take effect on the response only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.

    *)
  6. write_only : bool;
    (*

    Declares the property as "write only". Therefore, it MAY be sent as part of a request but SHOULD NOT be sent as part of the response. If the property is marked as writeOnly being true and is in the required list, the required will take effect on the request only. A property MUST NOT be marked as both readOnly and writeOnly being true. Default value is false.

    *)
  7. deprecated : bool;
    (*

    Specifies that a schema is deprecated and SHOULD be transitioned out of usage. Default value is false.

    *)
  8. additional : bool;
    (*

    Whether the property is part of the known fields (false) or whether the property represents all additional fields (true).

    *)
}

Object properties.

Sourcetype pathobj = OaTypes.pathobj = {
  1. pathobj_segs : pathobj_seg list;
  2. pathobj_item : path_item;
}

Path Object in the document.

Sourceand path_item = OaTypes.path_item = {
  1. path_item_summary : string option;
  2. path_item_description : string option;
  3. path_item_parameters : parameter list;
  4. path_item_kind : path_item_kind;
  5. get : operation option;
  6. put : operation option;
  7. post : operation option;
  8. delete : operation option;
  9. options : operation option;
  10. head : operation option;
  11. patch : operation option;
  12. trace : operation option;
}

Path Item Object in the document.

The parameters defined at the Path Item level are available at the deeper operation level, with Operation overrides applied.

All fields except path_item_kind are optional or have reasonable defaults.

Sourceand path_item_kind = OaTypes.path_item_kind =
  1. | PathItem_ref of Json_query.path
  2. | PathItemExt_ref of Restapis_o.Open__.Uri.t
  3. | PathItem
  4. | PathItemNone
    (*

    No path item which is allowed under OpenAPI Security Filtering

    *)
  5. | PathItemDummy
    (*

    For building cyclic definitions, a path object bound to a dummy will be considered absent for add_path and fold_all_paths but present for update_path. The idea is to insert a dummy path object, build a cyclic structure using it for recursion, and finally update the path object with the structure.

    *)
Sourceand operation = OaTypes.operation = {
  1. operation_summary : string option;
  2. operation_description : string option;
  3. operation_id : operation_id;
  4. operation_parameters : parameter list;
  5. operation_segs : operation_seg list;
  6. operation_request_body : request_body option;
  7. operation_responses : responses;
}

An Operation object in the document.

Sourceand operation_seg = OaTypes.operation_seg =
  1. | OpLiteralPart of string
  2. | OpFieldPart of {
    1. field_name : string;
    2. field_parameter : parameter;
    }
Sourceand request_body = OaTypes.request_body = {
  1. request_body_description : string option;
  2. request_body_content : (string * media_type) list;
  3. request_body_kind : request_body_kind;
}

A Request Body object.

All fields except request_body_kind are optional or have reasonable defaults.

Sourceand request_body_kind = OaTypes.request_body_kind =
  1. | RequestBody of request_body_specs
  2. | RequestBody_ref of Json_query.path
    (*

    A ref to a parameters object from its path in the JSON representation.

    *)
  3. | RequestBodyExt_ref of Restapis_o.Open__.Uri.t
  4. | RequestBodyDummy
    (*

    For building cyclic definitions, a request body bound to a dummy will be considered absent for add_request_body and fold_request_body but present for update_request_body. The idea is to insert a dummy parameter, build a cyclic structure using it for recursion, and finally update the request body with the structure.

    *)
Sourceand request_body_specs = OaTypes.request_body_specs = {
  1. request_body_required : bool;
}
Sourceand parameter = OaTypes.parameter = {
  1. parameter_description : string option;
    (*

    A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.

    *)
  2. parameter_deprecated : bool;
    (*

    Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.

    *)
  3. parameter_allow_empty_value : bool;
    (*

    Sets the ability to pass empty-valued parameters. This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false. If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.

    *)
  4. parameter_allow_reserved : bool;
    (*

    Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.

    *)
  5. parameter_schema : schema option;
  6. parameter_content : (string * media_type) option;
    (*

    A map containing the representations for the parameter. The key is the media type and the value describes it. The map MUST only contain one entry.

    *)
  7. parameter_kind : parameter_kind;
}

A Parameter object.

All fields except parameter_kind are optional or have reasonable defaults.

Sourceand parameter_kind = OaTypes.parameter_kind =
  1. | Parameter of parameter_specs
    (*

    The type of a Parameter.

    *)
  2. | Parameter_ref of Json_query.path
    (*

    A ref to a parameters object from its path in the JSON representation.

    *)
  3. | ParameterExt_ref of Restapis_o.Open__.Uri.t
  4. | ParameterDummy
    (*

    For building cyclic definitions, a parameter bound to a dummy will be considered absent for add_parameter and fold_operation_parameters but present for update_parameter. The idea is to insert a dummy parameter, build a cyclic structure using it for recursion, and finally update the parameter with the structure.

    *)
Sourceand parameter_specs = OaTypes.parameter_specs = {
  1. parameter_ref : param_ref;
  2. parameter_required : bool;
    (*

    Determines whether this parameter is mandatory. If the parameter location is "path", this property is REQUIRED and its value MUST be true. Otherwise, the property MAY be included and its default value is false.

    *)
  3. parameter_style : param_style;
    (*

    Describes how the parameter value will be serialized depending on the type of the parameter value. Default values (based on value of in): for query - form; for path - simple; for header - simple; for cookie - form.

    *)
  4. parameter_explode : bool;
    (*

    When this is true, parameter values of type array or object generate separate parameters for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. When style is form, the default value is true. For all other styles, the default value is false.

    *)
}
Sourceand responses = OaTypes.responses = {
  1. default_response : response option;
  2. coded_responses : (response_code * response) list;
}

A Responses object.

Sourceand response = OaTypes.response = {
  1. response_headers : (string * header) list;
  2. response_content : (string * media_type) list;
  3. response_kind : response_kind;
}

A Response object.

All fields except response_kind are optional or have reasonable defaults.

Sourceand response_kind = OaTypes.response_kind =
  1. | Response of response_specs
  2. | Response_ref of Json_query.path
    (*

    A ref to a parameters object from its path in the JSON representation.

    *)
  3. | ResponseExt_ref of Restapis_o.Open__.Uri.t
  4. | ResponseDummy
    (*

    For building cyclic definitions, a parameter bound to a dummy will be considered absent for add_response and fold_all_responses but present for update_response. The idea is to insert a dummy parameter, build a cyclic structure using it for recursion, and finally update the parameter with the structure.

    *)
Sourceand response_specs = OaTypes.response_specs = {
  1. response_description : string;
}
Sourceand header = OaTypes.header = {
  1. header_description : string option;
    (*

    A brief description of the parameter. This could contain examples of use. CommonMark syntax MAY be used for rich text representation.

    *)
  2. header_deprecated : bool;
    (*

    Specifies that a parameter is deprecated and SHOULD be transitioned out of usage.

    *)
  3. header_allow_empty_value : bool;
    (*

    Sets the ability to pass empty-valued parameters. This is valid only for query parameters and allows sending a parameter with an empty value. Default value is false. If style is used, and if behavior is n/a (cannot be serialized), the value of allowEmptyValue SHALL be ignored.

    *)
  4. header_allow_reserved : bool;
    (*

    Determines whether the parameter value SHOULD allow reserved characters, as defined by RFC3986 :/?#@!$&'()*+,;= to be included without percent-encoding. This property only applies to parameters with an in value of query. The default value is false.

    *)
  5. header_schema : schema option;
  6. header_kind : header_kind;
}

A Header object.

All fields except header_kind are optional or have reasonable defaults.

Sourceand header_kind = OaTypes.header_kind =
  1. | Header of header_specs
  2. | Header_ref of Json_query.path
    (*

    A ref to a parameters object from its path in the JSON representation.

    *)
  3. | HeaderExt_ref of Restapis_o.Open__.Uri.t
  4. | HeaderDummy
    (*

    For building cyclic definitions, a header bound to a dummy will be considered absent for add_header and fold_all_headers but present for update_header. The idea is to insert a dummy parameter, build a cyclic structure using it for recursion, and finally update the header with the structure.

    *)
Sourceand header_specs = OaTypes.header_specs = {
  1. header_required : bool;
    (*

    Determines whether this header is mandatory. Its default value is false.

    *)
  2. header_explode : bool;
    (*

    When this is true, header values of type array or object generate separate headers for each value of the array or key-value pair of the map. For other types of parameters this property has no effect. The default value is false.

    *)
}

The details for a header. The style is always simple.

Sourceand media_type = OaTypes.media_type = {
  1. media_type_schema : schema option;
}

A Media Type object.

Sourcetype primitive_kind = [
  1. | `PrimitiveString of string_specs
    (*

    A string (with optional characteristics).

    *)
  2. | `PrimitiveInteger of numeric_specs
    (*

    An int (with optional characteristics).

    *)
  3. | `PrimitiveNumber of numeric_specs
    (*

    A float (with optional characteristics).

    *)
  4. | `PrimitiveBoolean
    (*

    Any boolean.

    *)
  5. | `PrimitiveNull
    (*

    The null value.

    *)
  6. | `PrimitiveAny
    (*

    Any JSON value.

    *)
]

Primitive kind.

Sourceval pp_pathobj_seg : Restapis_o.Open__.Format.formatter -> pathobj_seg -> unit
Sourceval to_json_schema : t -> Json_schema.schema

to_json_schema t converts the OpenAPI schemas t to a JSON schema, possibly with a loss of information.

Schema Objects and combinators

Compliant OpenAPI specifications, unlike JSON Schema specs, do not have a root element. However, to support vendor extensions the root element has been exposed.

Compliant OpenAPI will have any as the root element, and uses Component Objects instead.

Sourceval schema : path:Json_query.path -> schema_kind -> schema

Construct a naked Schema object with all optional properties as None.

Sourceval create : schema -> t

Construct a schema from its root, without any component ; the element is checked not to contain any Def element.

Sourceval root_schema : t -> schema

Extract the root schema from an existing doc.

Sourceval update_schema : schema -> t -> t

Update a schema from its root, using the definitions from an existing schema ; the element is checked to contain only valid Def elements ; unused definitions are kept, see simplify_schema.

Sourceval self : t

Describes the implemented schema specification as a schema.

Sourceval any : t

A completely generic schema, without any component.

Sourceval combine : combinator -> t list -> t

Combines several schemas.

Schema Objects

Nomenclature: Schemas uses schema paths which are JSON pointers referencing locations in schema documents. There is another type of path ... the path object ... which is the path the client or browser sends to a server. The documentation will be easier to understand if you keep those paths separate in your mind.

Sourceval merge_schemas : (t * t) -> t * t

Merges the definitions of two schemas if possible and returns the updated schemas, so that their elements can be mixed without introducing dangling references ; if two different definitions are bound to the same path, Duplicate_schema will be raised.

Sourceval simplify_schema : t -> t

Remove the definitions that are not present in the document.

Sourceval add_schema : ?schemas_path:string -> string -> schema -> t -> t * schema

add_schema name schema t adds a Schema object by its name or document path name.

If name is an absolute path starting with a '/', it is untouched. Otherwise, it is considered relative to schemas_path (defaults to "#/components/schemas" as recommended by the OpenAPI standard). May raise Duplicate_schema if this path is already used or any error raised by Json_repr.path_of_json_pointer with ~wildcards:false.

Returns the modified document and the modified schema.

The modified schema will have a kind = Schema_ref _ that is a re-usable reference to the schema in the document.

Sourceval find_schema : ?schemas_path:string -> string -> t -> schema

find_schema name finds a Schema object by its document path.

May raise Not_found. See add_schema for the name format.

Sourceval schema_exists : ?schemas_path:string -> string -> t -> bool

Tells if a document path leads to a Schema object. See add_schema for the name format.

Sourceval schema_ref : ?schemas_path:string -> string -> schema

Build a reference to a Schema object. See add_schema for the name format.

Sourceval fold_all_schemas : t -> (schema -> 'a -> 'a) -> 'a -> 'a

fold_all_schemas t f init computes (f sN ... (f s1 init)...), where s1 ... sN are the schemas (in increasing schema_ref order).

When a Schema is a compound data type (array or object), only the root of the compound data type is folded. No array children are folded, and no object fields are folded. If you need a flattened traversal of compound data types, use OaSummary.datatypes with ~query_selector:`FlattenedAll instead.

Header Objects

Sourceval header : header_kind -> header

Construct a naked header (all optional properties to None).

Sourceval find_header : ?headers_path:string -> string -> t -> header

find_header name t finds a Header object by its name or document path name.

May raise Not_found. See add_header for the name format.

Sourceval find_header' : Json_query.path -> t -> header

find_header' path t finds a Header object by its document path path.

May raise Not_found.

Sourceval add_header : ?headers_path:string -> string -> header -> t -> t * header

add_header ?headers_path name header adds a Parameter object header by its name or document path name.

If name is an absolute path starting with a '/', it is untouched. Otherwise, it is considered relative to schemas_path (defaults to "#/components/headers" as recommended by the OpenAPI standard). May raise Duplicate_header if this path is already used or any error raised by Json_repr.path_of_json_pointer with ~wildcards:false.

Returns the modified document and the modified header.

The modified header will have a header_kind = Header_ref _ that is a re-usable reference to the header in the document.

Sourceval fold_all_headers : t -> (Json_query.path -> header -> 'a -> 'a) -> 'a -> 'a

fold_all_headers t f init computes (f kN dN ... (f k1 d1 init)...), where k1 ... kN are the document paths of all headers (in increasing order), and d1 ... dN are the associated headers.

Parameter Objects

Sourceval parameter : parameter_kind -> parameter

Construct a naked parameter (all optional properties to None).

Sourceval find_parameter : ?parameters_path:string -> string -> t -> parameter

find_parameter name t finds a Parameter object by its name or document path name.

May raise Not_found. See add_parameter for the name format.

Sourceval find_parameter' : Json_query.path -> t -> parameter

find_parameter' path t finds a Parameter object by its document path path.

May raise Not_found.

Sourceval find_operation_parameter : ?paths_path:string -> operation_id:operation_id -> param_name:string -> param_in:param_in -> t -> parameter

find_operation_parameter ~operation_id ~param_name ~param_in t finds the most specific Parameter for the parameter named param_name of the operation operation_id.

The most specific Parameter is the parameter attached to the operation at paths_path / path / operation / "parameters" if that exists. Otherwise the parameter paths_path / path / "parameters" is the most specific.

Sourceval add_parameter : ?parameters_path:string -> string -> parameter -> t -> t * parameter

add_parameter ?parameters_path name parameter adds a Parameter object parameter by its name or document path name.

If name is an absolute path starting with a '/', it is untouched. Otherwise, it is considered relative to schemas_path (defaults to "#/components/parameters" as recommended by the OpenAPI standard). May raise Duplicate_parameter if this path is already used or any error raised by Json_repr.path_of_json_pointer with ~wildcards:false.

Returns the modified document and the modified parameter.

The modified parameter will have a parameter_kind = Parameter_ref _ that is a re-usable reference to the parameter in the document.

Sourceval fold_all_parameters : t -> (Json_query.path -> parameter -> 'a -> 'a) -> 'a -> 'a

fold_all_request_bodies t f init computes (f kN dN ... (f k1 d1 init)...), where k1 ... kN are the document paths of all request bodies (in increasing order), and d1 ... dN are the associated request bodies.

Sourceval fold_operation_parameters : t -> (operation_id -> string -> param_in -> parameter -> 'a -> 'a) -> 'a -> 'a

fold_operation_parameters t f init computes (f oN nN lN pN ... (f o1 n1 l1 p1 init)...), where o1 ... oN are the Operations, n1 ... nN are the parameter names, l1 ... lN are the parameter locations, and p1 ... pN are the parameters.

Request Body Objects

Sourceval request_body : request_body_kind -> request_body

Construct a naked request_body (all optional properties to None).

Sourceval find_request_body : ?request_bodies_path:string -> string -> t -> request_body

find_request_body name t finds a Request Body object by its name or document path name.

May raise Not_found. See add_request_body for the name format.

Sourceval find_request_body' : Json_query.path -> t -> request_body

find_request_body' path t finds a Request Body object by its document path path.

May raise Not_found.

Sourceval add_request_body : ?request_bodies_path:string -> string -> request_body -> t -> t * request_body

add_request_body ?request_bodies_path name request_body adds a Request Body object request_body by its name or document path name.

If name is an absolute path starting with a '/', it is untouched. Otherwise, it is considered relative to schemas_path (defaults to "#/components/requestBodies" as recommended by the OpenAPI standard). May raise Duplicate_request_body if this path is already used or any error raised by Json_repr.path_of_json_pointer with ~wildcards:false.

Returns the modified document and the modified request body.

The modified request body will have a request_body_kind = Request_body_ref _ that is a re-usable reference to the request body in the document.

Sourceval fold_all_request_bodies : t -> (Json_query.path -> request_body -> 'a -> 'a) -> 'a -> 'a

fold_all_request_bodies t f init computes (f kN dN ... (f k1 d1 init)...), where k1 ... kN are the document paths of all request bodies (in increasing order), and d1 ... dN are the associated request bodies.

Sourceval fold_operation_request_bodies : t -> (operation_id -> request_body -> 'a -> 'a) -> 'a -> 'a

fold_operation_request_bodies t f init computes (f kN dN ... (f k1 d1 init)...), where k1 ... kN are the document paths of Operation objects' requestBody field (in increasing document path order), and d1 ... dN are the associated Request Body objects.

If there is no requestBody supplied for an Operation object, the operation is skipped.

Response Objects

Sourceval response : response_kind -> response

Construct a naked response (all optional properties to None).

Sourceval find_response : ?responses_path:string -> string -> t -> response

find_response name t finds a Parameter object by its name or document path name.

May raise Not_found. See add_response for the name format.

Sourceval add_response : ?responses_path:string -> string -> response -> t -> t * response

add_response ?responses_path name response adds a Parameter object response by its name or document path name.

If name is an absolute path starting with a '/', it is untouched. Otherwise, it is considered relative to schemas_path (defaults to "#/components/responses" as recommended by the OpenAPI standard). May raise Duplicate_response if this path is already used or any error raised by Json_repr.path_of_json_pointer with ~wildcards:false.

Returns the modified document and the modified response.

The modified response will have a response_kind = Response_ref _ that is a re-usable reference to the response in the document.

Sourceval fold_all_responses : t -> (Json_query.path -> response -> 'a -> 'a) -> 'a -> 'a

fold_all_responses t f init computes (f kN dN ... (f k1 d1 init)...), where k1 ... kN are the document paths of all Response objects (in increasing order), and d1 ... dN are the associated Response objects.

Sourceval fold_operation_responses : t -> (operation_id -> responses -> 'a -> 'a) -> 'a -> 'a

fold_operation_responses t f init computes (f kN dN ... (f k1 d1 init)...), where k1 ... kN are the document paths of Operation objects' responses field (in increasing document path order), and d1 ... dN are the associated Responses objects.

Path and Path Item Objects

Nomenclature: Path objects are the paths the client or browser sends to a server. There is another type of path .. the document path ... which is a JSON pointer referencing a location in a schema document. The documentation will be easier to understand if you keep those paths separate in your mind.

Sourceval path_item : path_item_kind -> path_item

Construct a naked Path Item (all optional properties to None).

Sourceval add_path : ?paths_path:string -> string -> path_item -> t -> t * path_item

add_path path_template item t adds a Path object that responds or requests URLs of the concrete path or path template path_template.

path_template is the object key within paths_path (defaults to "#/paths" as recommended by the OpenAPI standard). For example, when path_template = "v1/prices/{price}" the Path object is added as:

{
  paths: {
    "v1/prices/{price}": ...
  }
}

The item may have path_item_kind = PathItemNone for Security Filtering.

Returns the modified schema and the modified path item.

The modified path item will have a path_item_kind = PathItem_ref _ that is a re-usable reference to the path item in the document.

Sourceval fold_all_paths : t -> (pathobj_seg list -> path_item -> 'a -> 'a) -> 'a -> 'a

fold_all_paths t f init computes (f kN dN ... (f k1 d1 init)...), where k1 ... kN are the path segments of all Path objects (in ascending order of the number of field segments in the path), and d1 ... dN are the associated Path Item objects (which may have a path_item_kind = PathItemNone).

Paths with PathItemDummy items are skipped.

The ordering k1 is before kN conforms to the "before" matching ordering:

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/3.0.0.md#paths-object > When matching URLs, concrete (non-templated) paths would be matched > before their templated counterparts.

Predefined values

Sourceval array_specs : array_specs

Default Parameters of the Array and MonomorphicArray type specifiers.

Sourceval object_specs : path:Json_query.path -> object_specs

Default parameters of the Object type specifier.

Sourceval string_specs : string_specs

Default parameters of the String type specifier.

Sourceval numeric_specs : numeric_specs

Default parameters of the Integer and Number type specifiers.

Standard Extensions

The standard extensions provide a baseline of definitions that the vendor extensions can extend.

Sourcemodule type STANDARD = sig ... end

Vendor Extensions

Sourcemodule type VENDOR = sig ... end

JSON Serialization

Sourceval to_json : t -> Json_repr.ezjsonm

Formats OpenAPI schemas as its JSON representation.

This function works with JSON data represented in the Json_repr.ezjsonm format. See functor Make for using another representation.

Sourceval of_json : ?schemas_path:string -> ?parameters_path:string -> ?paths_path:string -> ?headers_path:string -> ?responses_path:string -> ?request_bodies_path:string -> Json_repr.ezjsonm -> t

Parse a JSON structure as OpenAPI schemas, if possible. May throw Cannot_parse.

This function works with JSON data represented in the Json_repr.ezjsonm format. See functor Make for using another representation.

Sourceval pp : Restapis_o.Open__.Format.formatter -> t -> unit

Formats OpenAPI schemas in human readable format.

Errors

Sourceexception Dangling_reference of Restapis_o.Open__.Uri.t

A reference to a non-existent location was detected.

Sourceexception Duplicate_schema of Json_query.path * schema * schema

A non-Dummy schema appeared twice on insertion or merge.

Sourceexception Duplicate_header of Json_query.path * header * header

A non-Dummy header appeared twice on insertion or merge.

Sourceexception Duplicate_request_body of Json_query.path * request_body * request_body

A non-Dummy request body appeared twice on insertion or merge.

Sourceexception Duplicate_response of Json_query.path * response * response

A non-Dummy response appeared twice on insertion or merge.

Sourceexception Duplicate_parameter of Json_query.path * parameter * parameter

The same parameter name and location (the in field) appeared twice on insertion or merge.

Sourceval print_error : ?print_unknown:(Restapis_o.Open__.Format.formatter -> exn -> unit) -> Restapis_o.Open__.Format.formatter -> exn -> unit

Produces a human readable version of an error.

Advanced interface for using a custom JSON representation

Sourcemodule Make (Repr : Json_repr.Repr) : sig ... end
include DkCoder_Std.SCRIPT
Sourceval __init : DkCoder_Std.Context.t -> unit

__init context is the entry point for running a script module. The DkCoder compiler will inject this function at the top and bottom of the script module. The top __init does nothing, while the bottom __init calls the prior __init.

That means:

  1. calling the __init function guarantees that the script module is initialized; that is, all of the script module's side-effects (ex. let () = Format.printf "Hello world@.") are executed before the __init returns to the caller.
  2. you can override the __init function by simply defining the __init idempotently. That will shadow the top __init and when the bottom __init is executed your __init will be called instead of the do-nothing top __init.

Future versions of DkCoder will call __init in dependency order for all `You script modules. Your __init function may be called several times.

Sourceval __repl : DkCoder_Std.Context.t -> unit

__repl context is the entry point for debugging a script module in a REPL. The DkCoder compiler will inject this function at the top and bottom of the script module. The top __repl does nothing, while the bottom __repl calls the prior __repl.

That means:

  1. you can override the __repl function by simply defining the __repl idempotently. That will shadow the top __repl and when the bottom __repl is executed your __repl will be called instead of the do-nothing top __repl.
Sourceval __module_info : unit -> DkCoder_Std.ModuleInfo.t

The run-time module information for the script module.