jumbf/README.md

# JUMBF Parser

This is a basic parser for the binary format described in ISO/IEC 19566-5. It is
intended to be a general-purpose library, but was created specifically for C2PA,
and only the features specifically needed for that use case have been developed
or tested.

## Supported features

### Parsing

-   [`ConsumeSuperBox(...)`](http://c2pa/jumbf/parse.h): Recursively parses a
    superbox and all contained boxes into
    [view-only structs](http://c2pa/jumbf/box.h).

-   Basic box structure: Complete

-   Box file format (Annex A): Complete

-   Content Types (Annex B): Partial, only supports:

    -   JSON (B.4)
    -   Embedded file (B.6)
    -   CBOR (B.7)
    -   C2PA Salt (Not defined by JUMBF, see C2PA 2.0 section 8.3.1.3)

    Other content types can be parsed, but will be returned as `UnknownBox`, and
    callers are responsible for interpreting the TBox value and handling the raw
    bytes appropriately.

-   References and requests (Annex C): Partial, only supports:

    -   Lookup of boxes by URI or path (C.2)

## Serialization

-   [`SuperBoxBuilder`](http://c2pa/jumbf/box_builder.h): Stateful builder for
    creating superboxes.

-   Basic box / superbox structure: Complete

-   Box file format (Annex A): Complete except for the following:

    -   Description box numerical IDs

    -   Description box hashes

-   Content Types (Annex B): All supported but callers are responsible for
    assembling raw payload and using the correct TBox value.

## Validation

This library is intentionally very permissive. It only validates box lengths and
the presence of description and content boxes within super boxes.

Callers are responsible for checking that content box types align with those
declared in description boxes.

## Super Box naming convention

The standard, somewhat confusingly, uses the term "JUMBF box" to refer to a
"superbox that shall contain exactly one JUMBF Description Box followed by one
or more JUMBF Content Boxes and at most one Padding Box." However, there are no
mentions anywhere in the standard of "superboxes" that are not "JUMBF Boxes".
So, for the sake of clarity, this library uses the term "Super Box" (in code as
"SuperBox" or "super_box") in place of the term "JUMBF box" as defined by the
standard.

## Directory structure

The public API is contained in the top-level directory, c2pa/jumbf. Internal
parsing functions are located in the
["internal" subdirectory](http://c2pa/jumbf/internal).

As a general rule, recursive parsing and assembling of the output format happens
in the top-level directory, while functions in the internal subdirectory handle
consuming the raw bytes.