ramlfications: RAML reference implementation in Python
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
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!
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:
0.1.4 (2015-05-27)
Added:
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.