urljsf

docs	install	build

Build statically-hostable, interactive HTML forms for making web requests

Powered by react-json-schema-form and react-bootstrap.

Visitors to a urljsf-built page see:

• one or more interactive HTML forms...
  • defined by and validated against a JSON Schema, optionally with...
  • deep customizable user interface
  • pre-filled data
  • custom validation checks

Once the data is validated, the user sees a button which gets a URL, which can be:

• downloaded as a file
• opened in a new browser window
• copy and pasted
• submitted to an HTTP endpoint, either by opening a new window, or directly.
• open native applications like email

urljsf doesn't ship a server, so that part is up to you!

Site builders write TOML, JSON, YAML or python, then can use urljsf as:

• a drop-in-and-pray script
• a standalone CLI tool
• a sphinx or mkdocs extension

... to create JavaScript/HTML forms that helps visitors provide good data for:

• pull requests
• issues
• galleries
• surveys
• on-demand build services
• precise test descriptions
• linter rules

Install

From PyPI

urljsf is distributed on PyPI, with several optional extras to help ensure tested versions are available:

pip install urljsf
# ... or    urljsf[sphinx]   for sphinx
# ... or    urljsf[mkdocs]   for mkdocs and pymdown-extensions
# ... or    urljsf[yaml]     for build time YAML parsing

# or...
uv install urljsf
# etc.

From conda-forge

urljsf is also distributed on conda-forge, with similar extras:

pixi add urljsf
# ... or urljsf-with-sphinx
# ... or urljsf-with-mkdocs
# ... or urljsf-with-yaml

# or...
micromamba install -c conda-forge urljsf
# or...
mamba install -c conda-forge urljsf
# or...
conda install -c conda-forge urljsf
# etc.

Development

See the contributing guide for a development install.

Usage

urljsf work with some JSON schema constrained files as a:

• (not-recommended) hot-linked script
• a standalone site generator for simple sites
• a plugin for the sphinx and mkdocs documentation systems

JSON Schema

A urljsf is built from a number of JSON schema-constrained files. Writing these in plain JSON is tedious, so TOML and YAML are also supported inputs for any of the methods below. Learn more on the schema documentation.

JS Script

A very simple, but limited, usage is an .html file that links to urljsf and bootstrap resources on the internet.

<script type="application/vnd.deathbeds.urljsf.v0+toml">
  [forms.url.schema]
  title = "pick an xkcd"
  description = "this will redirect to `xkcd.com`"
  type = "object"
  required = ["xkcd"]
  properties.xkcd = {type="integer", minimum=1, maximum=2997}

  [forms.url.ui_schema.xkcd."ui:options"]
  widget = "range"

  [templates]
  url = "https://xkcd.com/{{ data.url.xkcd }}"
  submit_button = "see xkcd #{{ data.url.xkcd }}"
</script>
<script
  type="module"
  src="https://deathbeds.github.io/urljsf/_static/index.js"
></script>

This technique has many limitations, and is not recommended.

Some ways to improve:

• download a GitHub release and unpack it, serving the files next to it
• ensure bootstrap is loaded before the script, with a link tag in a head.
• on the script element, use a src to point to a valid urljsf definition
• use the CLI or a documentation extension for sphinx or mkdocs

Command Line

The urljsf command line generates a ready-to-serve, standalone site with all required static assets. Written in python, it can reuse the extensive JSON schema support in the python ecosystem, such as msgspec or pydantic.

prsf --help

urljsf requires at least a definition file, but offers many command line options: see the documentation for more.

Sphinx

After installing with the [sphinx] extra, add urljsf.sphinxext to conf.py:

# conf.py
extensions = [
  # ... other extensions
  "urljsf.sphinxext",
]

Then use the urljsf directive in source files:

.. urljsf:  # a relative path to a description as a TOML, YAML, or JSON file or python
  :toml:
  # a form definition in TOML

See the documentation for more about configuring urljsf.sphinxext, the urljsf directive, and more advanced use cases.

Mkdocs

After installing with the [mkdocs] extra, add urljsf to mkdocs.yml:

# mkdocs.yml
plugins:
  - urljsf

Then use the urljsf fenced code block in source files:

```urljsf {path=path/to/defnition.toml}

```

See the documentation for more about configuring urljsf, the urljsf fence, and more advanced use cases.

Limitations

• react-json-schema-form cannot represent all possible data structures, such as writing a new JSON schema in JSON schema, or many features added after Draft 7
• the generated scripts won't work when served from file:// due to browser CORS headers requirements for type="module" scripts
• the sphinx integration is only tested with the html builder, the basic alabaster theme, and pydata-sphinx-theme (by way of urljsf's own documentation)
• the mkdocs integration is only tested with the default theme

Open Source

urljsf itself is licensed under the BSD-3-Clause license. You can do whatever you want with it, but if you change it a lot, it's not the maintainers' problem.

urljsf distributes third-party JavaScript and CSS in various forms, licensed under the MIT, BSD-3-Clause, and ISC licenses.