Expand description
The HPR open design format: a rocket design as one JSON document, with its JSON Schema.
The format’s page says what a document holds, how it’s versioned, and how it
was checked. The format is version 0.2, a draft until FusionSpace HPR’s first release, and a
document of version 0.1 is migrated when it’s read. The draft can change in place, so keep the
source .ork too.
A document is a DesignFile. It opens with a header naming the format (FORMAT), its
version (VERSION) and where the design came from (Provenance). Then comes the design as
hpr_io::ork reads it from a .ork. Last comes every other entry of that file’s archive,
such as an embedded thrust curve or a decal image.
The design holds the rocket, every motor configuration, the recovery events and the
simulations stored with it. What the source file holds that HPR Sim doesn’t model is kept
under a namespaced extension (x-openrocket). A .ork written from a document is the .ork
HPR Sim writes from the file it was read from, byte for byte. That was checked on the 73
designs HPR Sim’s .ork checks read (the format’s decision record).
to_json writes the canonical text: two-space indents, keys in the order the types declare
them, and a final newline. So the same design always gives the same bytes, and a change shows
as a small diff. from_json reads it back to the same value. It takes a document of an
older version to the current one (migrate). It refuses one of another format or a newer
version, with the reason. schema is the document’s JSON Schema, committed as
schema/format/hpr-design-0.2.schema.json beside the older versions’ schemas.
A container (.hprz) carries a design with other files, such as its flight logs.
TypeScript and Python programs read a document through types generated from the schema, under
schema/format/typescript/ and schema/format/python/. Each comes with a reader that checks a
document against the schema (the format page, the milestone that added
them).
use hpr_format::{DesignFile, Provenance, from_json, to_json};
let bytes = include_bytes!("../../../validation/fixtures/ork/loft-demo/demo-stable.ork");
let read = DesignFile::from_ork(bytes)?;
let text = to_json(&read.value)?;
assert!(text.starts_with("{\n \"format\": \"hpr-design\",\n \"version\": \"0.2\","));
assert_eq!(from_json(&text)?, read.value);Modules§
- container
- The
.hprzcontainer: a design and the files that go with it, such as flight logs, results and photographs, in one zip archive (ADR-112). - migrate
- Migrations: a document of an older version rewritten into the current version’s shape.
Structs§
- Design
File - A design as one document of the HPR design format.
- Opened
- A document read, and the version it was written in.
- Provenance
- Which program wrote a document, and from what.
- Source
- The file a design was read from: its format and its SHA-256, which name it without its path, and whether its rocket was read exactly as written.
- Source
File - One of the source file’s other files: its name, and its contents as text where they are UTF-8, or else as base64 (RFC 4648, section 4).
- Version
- A version of the format, written
major.minor(ADR-111).
Enums§
- Content
- A file’s contents: text, or base64 for bytes that are not UTF-8.
- Format
- The format’s name: a document holds only
hpr-design. - Format
Error - Why a document could not be written or read.
- Source
Format - The formats a design can be read from.
Constants§
- CONTAINER_
EXTENSION - The extension of the zip container of a design and its attachments (
container):.hprz. - EXTENSION
- The extension of a design written as plain JSON (ADR-111):
.hpr. - FORMAT
- The format’s name, the value of every document’s
formatkey. - MEDIA_
TYPE - The media type of a
.hprfile,application/vnd.fusionspace.hpr+json(ADR-199 §4): FusionSpace’s, in RFC 6838’s vendor tree, with the+jsonsuffix of a JSON document. Not registered with IANA. The extension (EXTENSION) and the format id (FORMAT) stay as they are. - VERSION
- The version this crate writes and reads.
Functions§
- from_
json - Reads a document from its JSON text, taking one of an older version to the current one.
- read_
json - Reads a document from its JSON text, and says which version it was written in.
- schema
- The document’s JSON Schema (draft 2020-12), as committed under
schema/format/. - schema_
json schemaas the canonical text committed: two-space indents and a final newline.- to_json
- The canonical JSON text of
document: two-space indents, keys in declared order, a final newline.