{"id":21065071,"url":"https://github.com/prolificinteractive/ballad","last_synced_at":"2025-12-29T21:37:10.471Z","repository":{"id":82618315,"uuid":"45861531","full_name":"prolificinteractive/ballad","owner":"prolificinteractive","description":"Assemble API Blueprint specs with concatenation, templating, and inheritance.","archived":false,"fork":false,"pushed_at":"2017-04-21T15:54:48.000Z","size":128,"stargazers_count":4,"open_issues_count":3,"forks_count":2,"subscribers_count":36,"default_branch":"master","last_synced_at":"2025-01-20T20:53:38.091Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/prolificinteractive.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2015-11-09T19:30:32.000Z","updated_at":"2017-09-28T17:33:32.000Z","dependencies_parsed_at":"2023-11-04T17:00:36.260Z","dependency_job_id":null,"html_url":"https://github.com/prolificinteractive/ballad","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prolificinteractive%2Fballad","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prolificinteractive%2Fballad/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prolificinteractive%2Fballad/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/prolificinteractive%2Fballad/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/prolificinteractive","download_url":"https://codeload.github.com/prolificinteractive/ballad/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243508986,"owners_count":20302106,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-19T17:53:22.715Z","updated_at":"2025-12-29T21:37:10.415Z","avatar_url":"https://github.com/prolificinteractive.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Ballad](ballad.jpg)\n\nAssemble API Blueprint specifications with concatenation, templating, and inheritance.\n\nBallad is designed to write API documentation quickly and easily, using composition and\nkeeping things [DRY](https://en.wikipedia.org/wiki/Don%27t_repeat_yourself).\n\nEach component of your specifications should be written with the [API Blueprint](https://apiblueprint.org/)\nformat. [Check out how to write Blueprints here](https://docs.apiary.io/api_101/api_blueprint_tutorial/).\n\nBallad was built with the [spoke-hub distribution paradigm](https://en.wikipedia.org/wiki/Spoke%E2%80%93hub_distribution_paradigm)\nin mind, meaning it easily allows the creation of API specifications derived from a base one, in an object-oriented manner.\n\nCheck out the example directory for sample specs, and view them live here:\n- [The Base Zoo Spec](http://htmlpreview.github.io/?https://github.com/prolificinteractive/ballad/blob/master/example/Zoo.html)\n- [The Bronx Zoo Spec that builds on the Zoo Spec](http://htmlpreview.github.io/?https://github.com/prolificinteractive/ballad/blob/master/example/Bronx_Zoo.html)\n\n\n\n# Table of Contents\n  1. [Installation](#installation)\n  2. [Setting Up a Spec](#setting-up-a-spec)\n  3. [JSON Helpers](./json-helpers.md)\n  4. [Usage Examples](./examples.md)\n  5. [Best Practices](./best_practices.md)\n  6. [Contributing](./contributing.md)\n\n## Installation\n\nNode.js and NPM are required. You must install node version 0.12 prior to running the install command:\n\n```bash\n$ npm install -g ballad\n```\n\n### build command\n\n```bash\n$ ballad build path/to/specs path/to/output.md\n```\n\nLoads `spec.json` at the root of `path/to/specs`, and generates a blueprint version of the spec.\n\n### docs command\n\n```bash\n$ ballad docs path/to/specs path/to/output.html\n```\n\nLoads `spec.json` at the root of the folder, and generates an HTML version of the spec.\n\n## Setting Up a Spec\n\nFirst we'll lay out a basic example, then explain the purpose of each directory and file.\n\n```\nspec/\n  spec.json\n  package.json\n  Makefile\n  overview.md\n  node_modules/\n  endpoints/\n    products.md\n  examples/\n    product.json\n  schemas/\n    product.json\n  models/\n    product.md\n  headers/\n    session.js\n```\n\n#### spec.json\n\nSpec files contain the complete map of your API, If you want a file to be available when\ncompiling your Blueprint, you must specify it here. We organize our files into endpoints,\nschemas, examples, and headers, each in their respective folders.\n\n```json\n{\n  \"name\": \"Prolific Store\",\n  \"inherit\": \"node_modules/pcf-specs\",\n  \"version\": \"1.1.0\",\n  \"features\": [\n    \"overview\",\n    \"endpoints/product\",\n    \"models/product\"\n  ],\n  \"excludeEndpoints\": {\n    \"/products/{id}/reviews\": [\n      \"POST\"\n    ]\n  }\n}\n```\nA spec.json file can contain:\n\n  - `name` - The name of the API.\n  - `inherit` (optional) - Path to base spec to inherit from. See [Extends and Inherits](#extends-and-inherits-helpers) Helpers for details.\n  - `version` - Semantic versioning of the specs (not the API).\n  - `features` - Markdown files at the given path within the base and child spec folders.\n  - `excludeEndpoints` (optional) - A map of endpoint paths to omit. If the value is an array, it will only omit those methods. If it is `true`, it will omit _all_ methods for that endpoint.\n\n#### package.json\n\nIf you plan on extending a public base spec, like `pcf-specs`, initiate an npm `package.json` file:\n```bash\n$ npm init\n```\n\nThen install the spec:\n```bash\n$ npm install pcf-specs`\n```\n\nThis will allow you to lock your spec to a specific version of the base spec using the `package.json` file.\n\n#### overview.md\n\nThe introductory part of the spec, including title:\n\n```\n# Prolific Commerce API\n\nThis is the Prolific Commerce API. Enjoy!\n```\n\n#### endpoints/\n\nThis holds the markdown files that will be concatenated together. They also allow you to use Handlebars templating, providing several helpers:\n\n```\n# Group Products\nThese are the endpoints regarding products.\n\n## Product [/products/{id}]\n\n### Get Product [GET]\nGets the full product model for the given id.\n\n+ Parameters\n\n  + id (required, string, `12345`) ... The id of the product.\n\n+ Response 200 (application/json; charset=utf-8)\n\n  + Body\n\n            {{example 'product'}}\n\n  + Schema\n\n            {{schema 'product'}}\n```\n\nThe `example` helper inserts the JSON from `examples/product.json`, while `schema` inserts the JSON from `schemas/product.json`.\nIf a file is found in both the base and child spec, they are automatically merged, with the child being given precedence.\n\n#### examples/\n\nHolds example JSON bodies that endpoints return. Below is an example file.\nNotice you can also use handlebars templating within a JSON file.\n\n```\n{\n  \"__exclude\": [\"rating\"],\n  \"reviews\": \"{{example 'reviewCollection'}}\",\n  \"materials\": [\n    \"cotton\",\n    \"polyester\"\n  ]\n}\n```\nOne caveat: If your example contains an array of objects, you need to make sure that\nyou always specify those objects in the same order, in both the child and base spec\nin order to properly merge them together. If you want to extend an array of objects with a new object, you must add blank\nobject placeholders (ie: {}), in the child array, and then any new objects you want to add.\n\nSee [JSON Helpers](./json-helpers.md) to learn about `__exclude` and other functions.\n\n#### schemas/\n\nIncludes body schemas to be included in endpoint files. These are optional,\nbut we find it useful to include them so you can use them for API validation.\nYou can use a tool like [this](http://jsonschemalint.com/) to test\nyour API.\n\n#### models/\n\nIncludes blueprint files that describe each model. These are typically appended\nat the end of the blueprint.\n\n```\n# Group Product Model\n\nDescription of the product model.\n\n{{example 'product'}}\n\n{{schema 'product'}}\n```\n\n#### Headers\n\nIncludes flat JSON files representing names and example values of headers.\n\n```\n{\n  \"sessionId\": \"a8d8f9ea108382374\"\n}\n```\n# Inheritance\n\nWe've modeled inheritance between a child and base spec as simply as possible. Any files\nthat appear in both the child and base specs will be merged together, with properties in\nthe child overriding properties in the base. This, combined with JSON helpers, lets you\neasily modify a base spec to suit your needs.\n\nIt's worth noting that the fact that child properties take precedence has a special implication\nwhen writing JSON schemas using version 4 of the specification. In this version, the required keys\nare specified in an array that corresponds to the value of a separate property called required.\nSaid key is treated as a regular non-object property and because of that for any modifications it\nmust be overridden with an array containing **all** object properties, own and/or inherited,\nintended to be obligatory. Non of the JSON helpers described in the following section has an\neffect over it so it has to be manually managed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprolificinteractive%2Fballad","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fprolificinteractive%2Fballad","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fprolificinteractive%2Fballad/lists"}