Frequently Asked Questions

RefPack is a standardized, secure, and versioned package format for distributing reference datasets. It's designed to make publishing, sharing, and consuming structured data (like country codes, currency tables, etc.) as seamless as installing a software library.

Each RefPack is a .zip file containing the data (data.json), a manifest (data.meta.json), a signature for the manifest (data.meta.json.jws), and optional files like a JSON schema, changelog, and readme. See the full specification for details.

While raw JSON/CSV files are easy to share, RefPack adds several crucial layers:

• Standardization: A consistent file structure means tools and applications can reliably understand any RefPack.
• Versioning: Semantic Versioning (SemVer) allows for clear tracking of changes and dependencies.
• Integrity & Authenticity: Manifests are signed with JWS, ensuring the metadata hasn't been tampered with and verifying the publisher (if a JWKS endpoint is used).
• Rich Metadata: The data.meta.json provides essential context like ID, title, authors, license, and creation date.
• Schema Validation: Optional data.schema.json allows consumers to validate the data's structure.
• Discoverability: RefPack registries (like this site) provide a central place to find and manage datasets.

The easiest way is to use the RefPack CLI tool. The refpack scaffold command creates a template directory, and refpack pack bundles and signs it.

You'll need to:

1. Prepare your data as a JSON array of objects (for data.json).
2. Fill in the manifest details in data.meta.json.
3. Optionally, create a data.schema.json, data.readme.md, and data.changelog.json.
4. Use the CLI to pack and sign. Refer to the Getting Started Guide and the CLI Guide.

data.meta.json.jws is a JSON Web Signature (JWS, RFC 7515) that digitally signs the data.meta.json manifest file.

Its importance lies in:

• Integrity: It guarantees that the manifest file (which describes the package contents, version, author, etc.) has not been altered since it was signed by the publisher.
• Authenticity: When validated against a publisher's public key (often via a JWKS URI), it confirms that the package was indeed published by that entity and not an imposter.

This helps build trust in the datasets you consume.

If you have an account on this RefPack Gallery, you can typically generate and manage API keys from your Account Settings page. API keys are used by the RefPack CLI (for push operations) or by other applications to interact with the registry's API programmatically.

Yes! The RefStor platform, which powers this gallery, is designed to be open source. You can clone the RefStor repository and follow its setup instructions to deploy your own instance. This allows for private or internal RefPack registries.

The ability to use a dataset for commercial purposes depends on its license. Each RefPack's data.meta.json manifest should specify a license (e.g., using an SPDX identifier like 'MIT', 'Apache-2.0', 'CC-BY-4.0').

Always check the license of a specific dataset before using it, especially in commercial projects, to ensure you comply with its terms. If no license is specified, you should assume it's proprietary and not available for reuse without explicit permission from the author.