Skip to main content

ramlfications: RAML reference implementation in Python

Latest Version Development Status License Current coverage Supported Python versions

Note: this project has been discontinued at Spotify and will be transferred to a new maintainer, we are currently finishing the transfer of this repository and the associated pypi package.

Requirements and Installation

User Setup

The latest stable version can be found on PyPI, and you can install via pip:

$ pip install ramlfications

ramlfications runs on Python 3.10+, and PyPy. Linux, OS X and Windows are supported. Both RAML 0.8 and RAML 1.0 are supported: the parser detects the version from the #%RAML header and dispatches automatically, so parse(), load(), and validate() work unchanged for both.

Continue onto usage to get started on using ramlfications.

Developer Setup

If you’d like to contribute or develop upon ramlfications, be sure to read How to Contribute first.

You can see the progress of ramlfications on our public project management page.

System requirements:

  • C Compiler (gcc/clang/etc.)

  • If on Linux - you’ll need to install Python headers (e.g. apt-get install python-dev)

  • Python 3.10+, or PyPy

  • virtualenv

Here’s how to set your machine up:

$ git clone git@github.com:jdiegodcp/ramlfications
$ cd ramlfications
$ virtualenv env
$ source env/bin/activate
(env) $ pip install -r dev-requirements.txt

Run Tests

If you’d like to run tests for all supported Python versions, you must have all Python versions installed on your system. I suggest pyenv to help with that.

To run all tests:

(env) $ tox

To run a specific test setup (options include: py310, py311, py312, pypy, flake8, manifest, docs, dev):

(env) $ tox -e py310

To run tests without tox:

(env) $ py.test
(env) $ py.test --cov ramlfications --cov-report term-missing

Build Docs

Documentation is built with Sphinx, written in rST, uses the Read the Docs theme with a slightly customized CSS, and is hosted on Read the Docs site.

To rebuild docs locally, within the parent ramlfications directory:

(env) $ tox -e docs

or:

(env) $ sphinx-build -b html docs docs/_build

Then within ramlfications/docs/_build you can open the index.html page in your browser.

Project History

Ramlfications was originally created by Spotify engineer github.com/econchick, but is currently not in use at Spotify. The project was discontinued in April 2022 and transferred to an external maintainer.

Still have issues?

Feel free to drop by #ramlfications on Freenode (webchat) or ping via Twitter[X]. “jdiegodcp” is the maintainer, a.k.a jdiegodcp on GitHub.

Changelog

0.3.0 (2026-10-25)

Added:

  • RAML 1.0 support, dispatched automatically from the #%RAML header at the existing parse()/load()/validate() entry points:

    • data types with inheritance, facets, and type expressions (named types, arrays T[], unions A | B)

    • annotationTypes declarations and annotations applied on resources and methods

    • uses libraries with dotted LibName.member references, including libraries used by other libraries

    • typed fragments (DataType, Trait, ResourceType, Library, SecurityScheme, DocumentationItem), parsed standalone or included

    • Overlay and Extension documents with RAML 1.0 merge semantics; overlays may not change behavioral aspects of their target

    • security scheme updates (RAML 1.0 OAuth 2.0 grants and null securedBy for optional security)

    • the RAML 1.0 parameter functions !uppercase, !lowercase, !lowercamelcase, !uppercamelcase, !lowerunderscorecase, !upperunderscorecase, !lowerhyphencase and !upperhyphencase (<<name | !uppercase>>); RAML 0.8 documents keep only !singularize and !pluralize

  • Version-routed validation: RAML 1.0-only constructs are rejected in 0.8 documents and vice versa, and RAML 1.0 rules (unresolvable type references, annotation value conformance) report located errors that are collected rather than failing at the first one.

Changed:

  • Python 3.10+ is now the minimum supported version; Python 2 era compatibility shims have been removed.

  • Dependencies modernized (PyYAML 6.x, current attrs).

  • A RAML 0.8 resource assigned a resource type with type: now gets that type’s required (non-?) methods, including those of the type’s own type:, as resource nodes. A resource that only declared type: used to produce a single node with method=None; it now produces one node per inherited method, so len(api.resources) grows for such APIs. Methods the resource declares itself keep their order and come first.

  • Validation follows the RAML specification where it was stricter: RAML 1.0 documents without baseUri validate (the spec makes it OPTIONAL); RAML 0.8 documents without baseUri validate when the config sets production = False (a missing production still requires it); APIs without resources validate; baseUriParameters accept any named-parameter type, not only string.

  • A placeholder name must match the parameter exactly: <<item-x>> is no longer treated as the parameter item.

Fixed:

  • RAML 0.8 resource type/trait inheritance edge cases, including optional (?) properties.

  • !include resolution (nested includes, relative paths, and missing-file errors).

  • <<resourcePathName>> is the rightmost path segment for nested resources (widget for /root/widget, previously root/widget) and is now also substituted when type: is a plain name.

  • Resource type and trait parameters (e.g. <<resourceType>>) are substituted in inherited scalar values such as description.

  • Inheriting a scalar value through a resource type that has its own type: no longer raises TypeError, and cyclic type: chains no longer raise RecursionError.

  • ramlfications tree -vv/-vvv lists form parameters declared under a form body (ResourceNode.form_params is unchanged).

  • A resource declared with no value (/empty:) parses as a resource without properties instead of raising AttributeError.

  • RAML 1.0 <<resourcePathName>> skips path segments that contain a URI parameter (users for /users/{id}), as the RAML 1.0 spec defines; RAML 0.8 keeps the rightmost segment ({id}).

  • Parameters a resource type passes to its own type: (e.g. type: {base: {thing: <<item>>}}) are substituted in what it inherits from that type.

  • A documentation value that is not a list, and unknown facets in a RAML 1.0 type declaration, raise InvalidRAMLStructureError instead of AssertionError / TypeError.

  • absolute_uri is a string (the resource path) when the API has no baseUri; it used to be a one-element list.

  • URI/base URI parameter handling (implicit template parameters and explicit overrides).

  • Passing a config file without a [main] validate option to parse() or ramlfications tree -c no longer turns validation off; such files now validate, as documented. To turn validation off, set validate = False (the older spelling validation is still accepted when validate is not set).

  • ramlfications tree -V/--validate now validates the file even when the config file turns validation off; the flag used to be ignored.

  • Placeholders next to each other are substituted independently: <<thing>>-<<resourcePathName>> gives gizmo-widgets instead of losing everything after gizmo.

  • !singularize and !pluralize leave a value that already has the requested form unchanged (/user with !singularize used to give False, and /users with !pluralize gave user).

  • An unknown parameter function, or a RAML 1.0 function in a RAML 0.8 document, raises InvalidRAMLStructureError naming the function instead of AttributeError/TypeError.

  • A parameter function applied to a number or boolean value (for example thing: 5 with <<thing | !uppercase>>) transforms its text form instead of raising AttributeError/TypeError.

0.1.9 (2015-12-24)

Happy holidays!

  • Fix resource type inheritance (Issue 23 & Issue 47)

  • Preserve order of baseUriParameters and uriParameters in API root and resource nodes (Issue 37)

  • Fix missing URI parameters if not defined/declared inline (Issue 56)

  • Fix how arguments are passed into pytest in setup.py (PR 55 - thank you matiasb!)

0.1.8 (2015-10-07)

  • Fix incorrect/incomplete behavior optional properties of Resource Types (Issue 44).

  • Fix protocols inheritance (Issue 44).

  • Partial fix for Issue 23 - incorrect resource type inheritance

    • When a resource type is defined with one method that is optional and is applied to a resource that does not have that method defined, the resource’s method should not inherit from the optional method

    • When a resource inherits a resource type but explicitly defines named parameters, the named parameters in the resource should overwrite those that are inherited

0.1.7 (2015-08-20)

Added:

0.1.6 (2015-08-03)

Added:

  • waffle.io page to documentation for project management overview

Fixed:

  • Parse errors when RAML file would have empty mappings (Issue 30)

  • Switch yaml.Loader to yaml.SafeLoader (Issue 26)

  • Update documentation to reflect rearrangement of errors (Issue 27)

  • Remove default parameter from being required for baseURIParameters (Issue 29)

  • Pin mock library for tox tests (Issue 22)

  • Experimenting with speeding up pypy tests within tox on Travis

0.1.5 (2015-06-05)

Fixed:

  • Configuration parsing for validation/production. Thanks vrajmohan!

  • Parsing of response bodies (fixes Issue 12). Thanks Igor!

0.1.4 (2015-05-27)

Added:

  • Support for recursive !includes in RAML files (0.1.3 would handle the error, now actually supports it. Thanks Ben for your PR!).

0.1.3 (2015-05-14)

Added:

  • New #ramlfications channel on freenode (web chat link)! Come chat, I’m lonely.

  • Documentation for configuration and the update command.

Fixed:

  • Handle recursive/cyclical !includes in RAML files for now (PR)

  • Encoding issues from upgrading to tox 2.0

  • tests/test_utils.py would create ramlfications/data/supported_mime_types.json; now mocked out.

0.1.2 (2015-04-21)

Fixed:

  • pypy 2.5.x would fail a parser test because order of list was not expected

0.1.1 (2015-04-21)

New:

  • Added ability to parse IANA-supported MIME media types

  • Added update command for user to update IANA-supported MIME types if/when needed

0.1.0a1 (2015-04-18)

Initial alpha release of ramlfications!

Metadata

Release files for ramlfications 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ramlfications 0.3.0
File Size Uploaded Provenance Actions
ramlfications-0.3.0.tar.gz 1.2 MB With provenance Details for ramlfications-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ramlfications 0.3.0
File Interpreter ABI Platform Actions
ramlfications-0.3.0-py3-none-any.whl Python 3 none any Details for ramlfications-0.3.0-py3-none-any.whl

Total release size: 1.3 MB

Release files / ramlfications-0.3.0.tar.gz

Download URL ramlfications-0.3.0.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
c1ac6630dd638599cf7b609d6b934d93b6f8f4dfe1e0e1e066f5265096d4bd85
BLAKE2b-256 checksum
How to use checksums
23a7694f8df01655e077cd2c3b7f987206996e827f2278c2228eb9de9871adc1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Release files / ramlfications-0.3.0-py3-none-any.whl

Download URL ramlfications-0.3.0-py3-none-any.whl
Size 84.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
8bc90371c3889b55f52eda45c8fcba8edaad581da6eb07fc71a30093e531f5f9
BLAKE2b-256 checksum
How to use checksums
6edcf65226c50a7ba9b0f7c4aa049ad0c3b4028d4de4995a578f4865368b34e8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

Security for ramlfications 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ramlfications-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 25, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page