Spec file format

Spec file format#

A spec file (.hf, .yaml, or .yml) defines your API: metadata, operations, SPARQL queries, and processing pipelines. RAMOSE parses it to route requests and generate documentation.

An HF file contains sections separated by blank lines. The first section defines the API. Each subsequent section defines an operation.

API section#

#url /v1
#type api
#base https://api.opencitations.net/meta
#title OpenCitations Meta REST API
#description REST API for bibliographic metadata from OpenCitations Meta
#version 1.1.1
#license [ISC](https://opensource.org/licenses/ISC)
#contacts [contact@opencitations.net](mailto:contact@opencitations.net)
#endpoint https://opencitations.net/meta/sparql
#method post
#addon metaapi

Field	Required	Description
`#url`	yes	API base path (e.g., `/v1`). Must be unique when multiple APIs coexist.
`#type`	yes	Must be `api`.
`#base`	yes	Full URL prefix shared across services.
`#title`	yes	API name shown in documentation.
`#description`	yes	Supports Markdown. Use `\n` for line breaks.
`#version`	yes	Version string.
`#license`	yes	License text. Markdown links supported.
`#contacts`	yes	Contact info in `[text](url)` format.
`#endpoint`	yes	Default SPARQL query endpoint URL.
`#update_endpoint`	no	SPARQL Update endpoint URL for write operations. Defaults to `#endpoint` when omitted.
`#method`	no	HTTP method for SPARQL requests: `get` or `post`. Default: `post`.
`#auth`	no	Set to `required` to make every operation in this API require a bearer token. Operation-level `#auth` overrides this default.
`#addon`	no	Python module name for custom functions. Path relative to the spec file.
`#sources`	no	Optional endpoint aliases for multi-source queries: `name1=url1; name2=url2`. Select an alias with `@@with name` or `@@with source=name`; select a direct URL with `@@with endpoint=...`.
`#disable_params`	no	Comma-separated list of built-in query parameters to suppress (`require`, `filter`, `sort`, `format`, `json`, `page`, `page_size`). Use `*` to disable all. Applies to all operations in this API. Operation-level `#disable_params` extends this set.
`#html_meta_description`	no	HTML meta description for documentation pages.

Operation section#

Each operation maps a URL pattern to a SPARQL query. Here is the /metadata/{ids} operation from the OpenCitations Meta API:

#url /metadata/{ids}
#type operation
#ids str((doi|issn|isbn|omid|openalex|pmid|pmcid):.+?(__(doi|issn|isbn|omid|openalex|pmid|pmcid):.+?)*$)
#preprocess generate_id_search(ids)
#postprocess create_metadata_output()
#method get
#description Returns bibliographic metadata for the given identifiers.
#call /metadata/doi:10.1162/qss_a_00292
#field_type str(id) str(title) str(author) datetime(pub_date) str(issue) str(volume) str(venue) str(page) str(type) str(publisher) str(editor)
#format xml,to_xml;turtle,to_turtle
#output_json [
    {
        "id": "doi:10.1162/qss_a_00292 omid:br/062104388184",
        "title": "OpenCitations Meta",
        "author": "Massari, Arcangelo [orcid:0000-0002-8420-0696 omid:ra/06250110138]; Mariani, Fabio [orcid:0000-0002-7382-0187 omid:ra/0621012370562]; Heibi, Ivan [orcid:0000-0001-5366-5194 omid:ra/0621012370563]; Peroni, Silvio [orcid:0000-0003-0530-4305 omid:ra/0621012370564]; Shotton, David [orcid:0000-0001-5506-523X omid:ra/0621012370565]",
        "pub_date": "2024",
        "issue": "1",
        "volume": "5",
        "venue": "Quantitative Science Studies [issn:2641-3337 openalex:S4210195326 omid:br/062501778099]",
        "type": "journal article",
        "page": "50-75",
        "publisher": "Mit Press [crossref:281 omid:ra/0610116105]",
        "editor": ""
    }
]
#sparql PREFIX datacite: <http://purl.org/spar/datacite/>
PREFIX literal: <http://www.essepuntato.it/2010/06/literalreification/>
PREFIX fabio: <http://purl.org/spar/fabio/>
...
SELECT DISTINCT ?id ?title ?author ?pub_date ... WHERE {
    [[ids]]
    ...
}

Field	Required	Description
`#url`	yes	Operation path with parameters in braces: `/path/{param}`.
`#type`	yes	Must be `operation`.
`#<param>`	no	Validator for a URL parameter. The field name matches the `{param}` in `#url`. Value is `type(regex)`, e.g. `#ids str(...)` validates `{ids}`. Defaults to `str(.+)` if omitted.
`#method`	yes	HTTP method(s). Space-separated for multiple (e.g., `get post`). `post`, `put`, `delete` are write operations (see Write operations). The same `#url` can have several operations with different methods.
`#description`	yes	Markdown-formatted description.
`#call`	yes	Example call URL with real parameter values. Shown in documentation.
`#field_type`	yes	Space-separated `type(field_name)` pairs defining output columns and their types.
`#output_json`	no	Example JSON response for documentation.
`#preprocess`	no	Preprocessing chain: `func1(param) --> func2(param)`. See addon modules.
`#postprocess`	no	Postprocessing chain: `func1() --> func2("arg")`. See addon modules.
`#sparql`	yes	SPARQL query. Parameters injected via `[[param_name]]` placeholders.
`#format`	no	Custom output format converters: `name,function;...`. See addon modules.
`#default_format`	no	Default output format when neither a `?format=` query parameter nor an `Accept` header selects one. Must match a name registered in `#format` or a built-in format (`csv`, `json`). Without this field, the default is JSON. When set to a custom format, the “Result fields type” section is hidden from the HTML documentation since the output structure does not match the tabular columns declared in `#field_type`.
`#custom_params`	no	Custom query parameters with addon handlers (`name,function,phase,description;...`) or YAML handlers (`name,file.yaml,description;...`). See addon modules.
`#disable_params`	no	Comma-separated list of built-in query parameters to suppress for this operation. Use `*` to disable all. Merged with any API-level `#disable_params`.
`#cache_duration`	no	Cache TTL in seconds for this operation. Overrides the global `--cache-ttl` value.
`#cache_disable`	no	Set to any value (e.g., `true`) to disable caching for this operation.
`#retry_attempts`	no	Total SPARQL read attempts for this operation, including the first one. Applies to standard SPARQL and SPARQL Anything reads. Overrides the `APIManager` or CLI value. Use `1` to disable retries.
`#retry_wait`	no	Seconds to wait before the first SPARQL read retry for this operation. Applies to standard SPARQL and SPARQL Anything reads. Overrides the `APIManager` or CLI value.
`#retry_backoff`	no	Multiplier applied between SPARQL read retry waits for this operation. Applies to standard SPARQL and SPARQL Anything reads. Overrides the `APIManager` or CLI value.
`#auth`	no	Set to `required` to require a bearer token for this operation. Overrides the API-level `#auth`.

YAML format#

YAML spec files are an alternative source format for the same RAMOSE API definition. They are not the OpenAPI YAML export. The top-level YAML value is a list: the first item is the API section, and each following item is an operation. Field names match HF names without the leading #.

- url: /v1
  type: api
  base: https://api.opencitations.net/meta
  title: OpenCitations Meta REST API
  description: REST API for bibliographic metadata from OpenCitations Meta
  version: "1.1.1"
  license: ISC
  contacts: contact@opencitations.net
  endpoint: https://opencitations.net/meta/sparql
  method: post

- url: /metadata/{ids}
  type: operation
  ids: 'str((doi|issn|isbn|omid|openalex|pmid|pmcid):.+)'
  preprocess: generate_id_search(ids)
  method: get
  description: |
    Returns bibliographic metadata for the given identifiers.
  call: /metadata/doi:10.1162/qss_a_00292
  field_type: str(id) str(title) datetime(pub_date)
  retry_attempts: "3"
  retry_wait: "0.5"
  retry_backoff: "2.0"
  output_json: |
    [
      {
        "id": "doi:10.1162/qss_a_00292",
        "title": "OpenCitations Meta",
        "pub_date": "2024"
      }
    ]
  sparql: |
    SELECT DISTINCT ?id ?title ?pub_date WHERE {
      [[ids]]
    }

All YAML field values are read as strings. Quote values that YAML would otherwise parse as numbers, booleans, lists, or maps. Use block scalars (|) for multi-line fields such as description, output_json, and sparql.

Supported types#

Used in #field_type declarations and #<param> definitions:

Type	Cast behavior	Default for missing values
`str`	Lowercase string	Empty string
`int`	Integer	Minimum integer
`float`	Float	Minimum float
`datetime`	ISO 8601 date	`0001-01-01`
`duration`	XML Schema duration	`P2000Y`
`iri`	String kept verbatim; in write operations the value is validated as an IRI	Empty string
`literal`	String kept verbatim; in write operations the value is escaped as a SPARQL string literal	Empty string

iri and literal behave like str for read operations but skip the lowercasing, and they drive safe value binding for write operations (see below).

Parameter substitution#

In #sparql blocks, [[param_name]] placeholders are replaced with the URL parameter value before query execution. The parameter name matches the {param} in the operation URL.

Write operations#

An operation whose #method is post, put, or delete runs a SPARQL 1.1 Update (INSERT/DELETE/UPDATE) instead of a read query. The update is sent to #update_endpoint (or #endpoint if that is not set) and the response is a small JSON confirmation rather than a result set.

Here is an example:

#url /resources
#type operation
#method post
#auth required
#resource iri(.+)
#title literal(.+)
#identifier iri(.+)
#scheme iri(.+)
#value literal(.+)
#description Create a bibliographic resource with a title and an identifier
#field_type str(x)
#sparql INSERT DATA {
            <[[resource]]> a <http://purl.org/spar/fabio/Expression> ;
                <http://purl.org/dc/terms/title> "[[title]]" ;
                <http://purl.org/spar/datacite/hasIdentifier> <[[identifier]]> .
            <[[identifier]]> a <http://purl.org/spar/datacite/Identifier> ;
                <http://purl.org/spar/datacite/usesIdentifierScheme> <[[scheme]]> ;
                <http://www.essepuntato.it/2010/06/literalreification/hasLiteralValue> "[[value]]" .
        }

POST /resources
Authorization: Bearer <token>
Content-Type: application/json

{
  "resource": "https://w3id.org/oc/meta/br/062104388184",
  "title": "OpenCitations Meta",
  "identifier": "https://w3id.org/oc/meta/id/062106312420",
  "scheme": "http://purl.org/spar/datacite/doi",
  "value": "10.1162/qss_a_00292"
}

The same request can carry the parameters in the URL query string instead of a body. With curl, --url-query encodes each value for you:

curl -X POST http://127.0.0.1:8080/bibliography/v1/resources \
  -H "Authorization: Bearer <token>" \
  --url-query 'resource=https://w3id.org/oc/meta/br/062104388184' \
  --url-query 'title=OpenCitations Meta' \
  --url-query 'identifier=https://w3id.org/oc/meta/id/062106312420' \
  --url-query 'scheme=http://purl.org/spar/datacite/doi' \
  --url-query 'value=10.1162/qss_a_00292'

Or with everything inline in the URL (spaces must be percent-encoded as %20; : and / may stay as they are):

curl -X POST "http://127.0.0.1:8080/bibliography/v1/resources?resource=https://w3id.org/oc/meta/br/062104388184&title=OpenCitations%20Meta&identifier=https://w3id.org/oc/meta/id/062106312420&scheme=http://purl.org/spar/datacite/doi&value=10.1162/qss_a_00292" \
  -H "Authorization: Bearer <token>"

If any [[placeholder]] is left unfilled after substitution, the request is rejected with HTTP 400 and nothing is sent to the endpoint.

Protect write operations with #auth required; see authentication.