Skip to main content

Crate hpr_format

Crate hpr_format 

Source
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 .hprz container: 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§

DesignFile
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.
SourceFile
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.
FormatError
Why a document could not be written or read.
SourceFormat
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 format key.
MEDIA_TYPE
The media type of a .hpr file, application/vnd.fusionspace.hpr+json (ADR-199 §4): FusionSpace’s, in RFC 6838’s vendor tree, with the +json suffix 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
schema as 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.