Indexed by TopGit from live GitHub metadata: interagent/prmd has 2.1k stars, written primarily in Ruby. JSON Schema tools and doc generation for HTTP APIs
Snapshot summary built from the project's own GitHub metadata — there's no written TopGit review yet. The page will update automatically when a full review is published.
WHY NO REVIEW YET
TopGit writes full reviews for the most-starred, most-requested repositories. This page is a snapshot until then — see the READ ME tab for the original README in full.
JSON Schema tooling: scaffold, verify, and generate documentation
from JSON Schema documents.
Introduction
JSON Schema provides a great way to describe
an API. prmd provides tools for bootstrapping a description like this,
verifying its completeness, and generating documentation from the
specification.
To learn more about JSON Schema in general, start with
this excellent guide
and supplement with the specification.
The JSON Schema usage conventions expected by prmd specifically are
described in /docs/schemata.md.
Installation
Install the command-line tool with:
$ gem install prmd
If you're using prmd within a Ruby project, you may want to add it
to the application's Gemfile:
gem 'prmd'
$ bundle install
Usage
Prmd provides four main commands:
init: Scaffold resource schemata
combine: Combine schemata and metadata into single schema
verify: Verify a schema
doc: Generate documentation from a schema
render: Render views from schema
Here's an example of using these commands in a typical workflow:
# Fill out the resource schemata
$ mkdir -p schemata
$ prmd init app > schemata/app.json
$ prmd init user > schemata/user.json
$ vim schemata/{app,user}.json # edit scaffolded files
# Provide top-level metadata
$ cat <<EOF > meta.json
{
"description": "Hello world prmd API",
"id": "hello-prmd",
"links": [{
"href": "https://api.hello.com",
"rel": "self"
}],
"title": "Hello Prmd"
}
EOF
# Combine into a single schema
$ prmd combine --meta meta.json schemata/ > schema.json
# Check it’s all good
$ prmd verify schema.json
# Build docs
$ prmd doc schema.json > schema.md
Using YAML instead of JSON as a resource and meta format
init and combine supports YAML format:
# Generate resources in YAML format
$ prmd init --yaml app > schemata/app.yml
$ prmd init --yaml user > schemata/user.yml
# Combine into a single schema
$ prmd combine --meta meta.json schemata/ > schema.json
combine can detect both *.yml and *.json and use them side by side. For example, if one have a lot of legacy JSON resources and wants to create new resources in YAML format - combine will be able to handle it properly.
{
"doc": {
"url_style": "default", // can also be "json"
"disable_title_and_description": false, // remove the title and the description, useful when using your own custom header
"toc": false // insert the table of content for json scheme documentation to the top of the file. (default disable)
}
}
Use as rake task
In addition, prmd can be used via rake tasks
# Rakefile
require 'prmd/rake_tasks/combine'
require 'prmd/rake_tasks/verify'
require 'prmd/rake_tasks/doc'
namespace :schema do
Prmd::RakeTasks::Combine.new do |t|
t.options[:meta] = 'schema/meta.json' # use meta.yml if you prefer YAML format
t.paths << 'schema/schemata/api'
t.output_file = 'schema/api.json'
end
Prmd::RakeTasks::Verify.new do |t|
t.files << 'schema/api.json'
end
Prmd::RakeTasks::Doc.new do |t|
t.files = { 'schema/api.json' => 'schema/api.md' }
end
end
task default: ['schema:combine', 'schema:verify', 'schema:doc']
File Layout
We suggest the following file layout for JSON schema related files:
/docs (top-level directory for project documentation)
/schema (API schema documentation)
/schemata
/{resource.[json,yml]} (individual resource schema)
/meta.[json,yml] (overall API metadata)
/overview.md (preamble for generated API docs)
/schema.json (complete generated JSON schema file)
/schema.md (complete generated API documentation file)
where [json,yml] means that it could be either json or yml.
Contributing
Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Add some feature')
Push to the branch (git push origin my-new-feature)
No homepage URL was recorded for interagent/prmd in TopGit's last sync. The README tab above frequently contains screenshots and demo links, or check the repository description on GitHub.
Does interagent/prmd have any tags?
TopGit's last sync did not record any GitHub topics for interagent/prmd. GitHub topics appear in the right sidebar of a repository page; that's the authoritative place to check.
How active is development on interagent/prmd?
The most recent commit recorded on interagent/prmd was 1.8 years ago, based on the GitHub push timestamp. The repository has 169 forks — one of the better signals of community interest.
How many stars does interagent/prmd have?
interagent/prmd has 2.1k GitHub stars — refresh the page for the live number, or check github.com/interagent/prmd. TopGit mirrors GitHub's count but does not claim minute-by-minute accuracy.
Is interagent/prmd open source?
Yes — interagent/prmd ships under the MIT license, which makes its source code freely readable (and, depending on license terms, forkable and reusable). Source: github.com/interagent/prmd.
Where do I read more about interagent/prmd?
This TopGit page is a snapshot — the READ ME tab shows the project's own README content (links stripped, images preserved). The GitHub repository at github.com/interagent/prmd is the definitive source.
Read full README in the tab above.
Curious whether prmd is right for you?
Let ChatGPT, Claude, or Perplexity look into it — click below and see what AI actually says about prmd.