Skip to content
cadkithome

Document JSON schema (v1)

Every cadkit interface can export a drawing as JSON in one shape: the format-neutral Document model of cadkit-core. This page lists that shape, field by field, as version 1 of the layout. It is generated from the committed JSON Schema (document-v1.schema.json, draft 2020-12), which cadkit-core derives from the Rust types with its optional schemars feature.

Exported JSON carries schema_version: 1; JSON without the field reads as version 1. The version increases only when an existing field changes meaning or shape. New optional fields do not change it, so consumers should ignore fields they do not know. The Rust importer (document_from_json, which the bindings call) rejects other versions. See the architecture notes for coordinate and unit conventions and the 0.5 migration notes for model changes.

Interface Export Import
Rust cadkit::to_json(&doc, pretty) cadkit::export::document_from_json(text, &limits)
Python doc.to_json(pretty=True), doc.to_dict() cadkit.Document.from_json(text) (reference)
JavaScript doc.toJsonString(true), doc.toJSON() CadDocument.fromJsonString(text) (reference)
C cadkit_document_to_json(doc, 1, &json) cadkit_document_from_json(json, &doc) (reference)
CLI cadkit convert plan.dxf plan.json --pretty, cadkit dump --json plan.dxf

The raw schema is served at /schema/document-v1.schema.json for validators and editors; its source is docs/schema/document-v1.schema.json.

A complete drawing.

Field Type Required Description
blocks array of Block yes Block definitions (DWG/DXF blocks, DGN shared cell definitions).
layers array of Layer yes Layers (DWG/DXF layers, DGN levels).
linetypes array of Linetype yes Linetype definitions.
models array of Model yes Model spaces, layouts and sheets that hold the drawn entities.
props map of Value yes Document-level extras (header variables, file properties).
schema_version SchemaVersion no Version of this JSON layout; see SchemaVersion.
source SourceInfo yes Where the data came from.
text_styles array of TextStyle yes Text style definitions.
units Units yes Unit of all coordinates in this document.
warnings array of Warning yes Recoverable problems met while reading. A non-empty list does not mean failure.

Multi-line text attachment point.

Type: "top_left", "top_center", "top_right", "middle_left", "middle_center", "middle_right", "bottom_left", "bottom_center", "bottom_right".

Non-graphic data attached to an entity (DWG ATTRIB, DGN tag, item-type property).

Field Type Required Description
color Color or null no Color of the attribute’s own record when the format stores one that differs from the owning entity’s (a DGN tag element has its own symbology; the DGN reader resolves it through the file’s color table as it does for entities). None uses the owning entity’s color.
display AttributeDisplay or null no How the value text is drawn at position; None when unknown or not drawn.
invisible boolean yes The attribute is not displayed.
layer string or null no Layer of the attribute’s own record when the format stores one (a DGN tag element has its own level). None uses the owning entity’s layer.
lineweight Lineweight or null no Lineweight of the attribute’s own record when the format stores one that differs from the owning entity’s. None uses the owning entity’s lineweight.
position Point3 or null no Where the attribute text is displayed, if it is displayed.
props map of Value no Format-specific data with no neutral field (e.g. dgn.color_index, dgn.weight).
set string or null no Owning tag set / item type / definition name.
tag string yes Tag / property name.
value Value yes Value.

Text presentation of a displayed attribute value.

Field Type Required Description
halign HAlign yes Horizontal alignment of the text about Attribute::position.
height number (double) yes Text height, in drawing units.
rotation number (double) yes Rotation about the drawing Z axis, in radians.
style string or null no Text style (DGN font) name; None leaves the choice to the writer’s default.
valign VAlign yes Vertical alignment of the text about Attribute::position.
width number (double) yes Character width, in drawing units (DGN stores it separately from the height).

A block definition (DGN: shared cell definition).

Field Type Required Description
base_point Point3 yes Insertion base point.
description string or null no Description text.
entities array of Entity yes Entities in block coordinates.
id integer (uint64) or null no Native identifier.
is_xref boolean yes Block is an external reference.
name string yes Unique name.
props map of Value yes Format-specific extras.
xref_path string or null no Path of the external reference.

Color.

Tagged by type. Variants:

Use the layer color.

Use the color of the inserting block reference.

AutoCAD Color Index 1..=255. DGN palette indices are resolved to Color::Rgb by the DGN reader; the original index goes to props["dgn.color_index"].

Field Type Required Description
index integer (uint8) yes Index.

True color.

Field Type Required Description
b integer (uint8) yes Blue.
g integer (uint8) yes Green.
r integer (uint8) yes Red.

Dimension kind.

Type: "linear", "aligned", "angular", "angular3_point", "diameter", "radius", "ordinate", "arc_length", "other".

One drawn object.

Field Type Required Description
attributes array of Attribute yes Attached non-graphic data: DWG attributes, DGN tags, item-type properties.
color Color yes Color.
id integer (uint64) or null no Native identifier (DWG handle, DGN element id).
kind EntityKind yes Geometry and type-specific data.
layer string or null no Layer name; None means the default layer.
linetype string or null no Linetype name; None means by layer.
lineweight Lineweight yes Lineweight.
props map of Value yes Format-specific extras.
raw Raw or null no Original record bytes, kept only when crate::ReadOptions::keep_raw is set.
visible boolean yes Entity is displayed.

Geometry and type-specific data of an Entity.

Tagged by type. Variants:

A point.

Field Type Required Description
position Point3 yes Location.

A straight segment.

Field Type Required Description
end Point3 yes End point.
start Point3 yes Start point.

Connected segments, optionally with arc segments (bulge) and widths. Covers DWG LWPOLYLINE/POLYLINE and DGN line string / shape.

Field Type Required Description
closed boolean yes Last vertex connects back to the first.
normal Vec3 yes Plane normal; bulge arcs turn counter-clockwise about it. +Z for plain 2D data and for non-planar 3D polylines (which have no bulges).
vertices array of Vertex yes Vertices in order.

A full circle.

Field Type Required Description
center Point3 yes Center.
normal Vec3 yes Plane normal.
radius number (double) yes Radius.

A circular arc from start_angle counter-clockwise to end_angle.

Field Type Required Description
center Point3 yes Center.
end_angle number (double) yes End angle in radians.
normal Vec3 yes Plane normal.
radius number (double) yes Radius.
start_angle number (double) yes Start angle in radians.

An ellipse or elliptical arc.

Field Type Required Description
center Point3 yes Center.
end_param number (double) yes End parameter in radians (2π for a full ellipse).
major_axis Vec3 yes Vector from the center to the end of the major axis (its length is the semi-major axis).
normal Vec3 yes Plane normal.
ratio number (double) yes Minor / major axis ratio, in (0, 1].
start_param number (double) yes Start parameter in radians (0 for a full ellipse).

A B-spline / NURBS curve.

Field Type Required Description
closed boolean yes Curve is closed / periodic.
control_points array of Point3 yes Control points.
degree integer (uint32) yes Degree.
fit_points array of Point3 yes Fit points, if stored.
knots array of number (double) yes Knot vector (may be empty when only fit points are known).
weights array of number (double) yes Weights; empty for non-rational curves.

Single-line text.

Field Type Required Description
end_point Point3 or null no Baseline end for Aligned/Fit text; None for every other alignment.
halign HAlign yes Horizontal alignment.
height number (double) yes Character height.
normal Vec3 yes Plane normal.
oblique number (double) yes Oblique angle in radians.
position Point3 yes Anchor point implied by halign/valign: the baseline start for left/baseline text, otherwise the justification point (DXF/DWG second alignment point, group 11). For Aligned/Fit text: the baseline start.
rotation number (double) yes Rotation in radians.
style string or null no Text style name.
valign VAlign yes Vertical alignment.
value string yes Decoded text.
width_factor number (double) yes Width factor (1.0 = normal).

Multi-line, formatted text. DGN text nodes map to this when they only hold text.

Field Type Required Description
attachment Attachment yes Attachment point.
height number (double) yes Character height.
line_spacing number (double) yes Line spacing factor.
normal Vec3 yes Plane normal.
plain string yes Text with format codes removed, lines separated by \n.
position Point3 yes Insertion point.
rotation number (double) yes Rotation in radians.
style string or null no Text style name.
value string yes Text including format codes as stored.
width number (double) yes Reference rectangle width, 0 when unconstrained.

A placed block (DWG INSERT, DGN shared cell instance). Attribute values live in Entity::attributes.

Field Type Required Description
block string yes Block name.
column_spacing number (double) yes Column spacing.
columns integer (uint32) yes Array columns (1 = no array).
normal Vec3 yes Plane normal.
position Point3 yes Insertion point.
rotation number (double) yes Rotation in radians.
row_spacing number (double) yes Row spacing.
rows integer (uint32) yes Array rows (1 = no array).
scale Vec3 yes Scale factors.

A filled or patterned area.

Field Type Required Description
loops array of HatchLoop yes Boundary loops; the first is usually the outer one.
normal Vec3 yes Plane normal.
pattern string or null no Pattern name, if patterned.
pattern_angle number (double) yes Pattern angle in radians.
pattern_scale number (double) yes Pattern scale.
solid boolean yes Solid fill.

A dimension annotation.

Field Type Required Description
block string or null no Anonymous block holding the rendered dimension, if any.
dimension_type DimensionType yes Kind of dimension.
measurement number (double) or null no Measured value in drawing units (or radians for angular).
points array of Point3 yes Definition points in format order (see props for their roles).
style string or null no Dimension style name.
text string or null no Text override.
text_position Point3 or null no Text middle point.

A planar 3- or 4-sided face (DWG SOLID/TRACE/3DFACE).

Field Type Required Description
filled boolean yes The face is filled (SOLID/TRACE) rather than a wire face.
points array of Point3 yes Corner points (3 or 4).

A planar surface with optional holes, in world coordinates (WCS) and drawing units. Each ring is explicitly closed by repeating its first point as its last point.

Field Type Required Description
exterior array of Point3 yes Closed outer boundary ring containing at least four positions.
interiors array of array of Point3 yes Closed hole rings inside the exterior boundary.

A leader line.

Field Type Required Description
arrowhead boolean yes Draws an arrowhead at the first vertex.
vertices array of Point3 yes Vertices from arrow tip to the end.

A raster image reference (DWG IMAGE, DGN raster attachment).

Field Type Required Description
path string or null no Image file path as stored.
position Point3 yes Lower-left corner.
size_px array of integer (uint32) or null no Pixel size, when known.
u_vector Vec3 yes Vector along the image bottom edge, covering the full width.
v_vector Vec3 yes Vector along the image left edge, covering the full height.

A paper-space viewport.

Field Type Required Description
center Point3 yes Center on the sheet.
height number (double) yes Height on the sheet.
view_center Point3 yes Model-space point shown at the center.
view_height number (double) yes Model-space height shown.
width number (double) yes Width on the sheet.

A polygon mesh or polyface.

Field Type Required Description
faces array of array of integer (uint32) yes Faces as vertex indices (0-based).
vertices array of Point3 yes Vertex positions.

Entities that belong together: DGN complex chains/shapes, cells, text nodes, groups. Children are in the same coordinate space as the group.

Field Type Required Description
children array of Entity yes Member entities.
group_kind GroupKind yes What kind of grouping this is.
name string or null no Name (cell name, group name).
origin Point3 or null no Origin (cell origin, text node origin).

A record the reader recognized but does not model; see props / raw.

Field Type Required Description
type_name string yes Native type name or code, e.g. "dgn.type_94" or "dwg.ACAD_TABLE".

File format family.

Type: "unknown" or "dwg" or "dxf" or "dgn_v7" or "dgn_v8" or "city_gml".

  • "unknown": Not known (e.g. a document built in memory).
  • "dwg": AutoCAD DWG.
  • "dxf": AutoCAD DXF (ASCII or binary).
  • "dgn_v7": MicroStation DGN V7 (ISFF).
  • "dgn_v8": MicroStation DGN V8 (OLE compound file).
  • "city_gml": CityGML 2.0 (XML application schema based on GML 3.1.1).

What a EntityKind::Group represents.

Type: "complex_chain" or "complex_shape" or "text_node" or "cell" or "other".

  • "complex_chain": DGN complex chain (open).
  • "complex_shape": DGN complex shape (closed).
  • "text_node": DGN text node.
  • "cell": DGN cell (children inline, already placed).
  • "other": Any other grouping.

Horizontal text alignment.

Type: "left", "center", "right", "aligned", "middle", "fit".

A hatch boundary edge.

Tagged by type. Variants:

Field Type Required Description
end Point3 yes
start Point3 yes
Field Type Required Description
ccw boolean yes
center Point3 yes
end_angle number (double) yes
radius number (double) yes
start_angle number (double) yes
Field Type Required Description
ccw boolean yes
center Point3 yes
end_param number (double) yes
major_axis Vec3 yes
ratio number (double) yes
start_param number (double) yes
Field Type Required Description
control_points array of Point3 yes
degree integer (uint32) yes
knots array of number (double) yes
weights array of number (double) yes
Field Type Required Description
closed boolean yes
vertices array of Vertex yes

One hatch boundary loop.

Field Type Required Description
edges array of HatchEdge yes Edges in order.
external boolean yes Loop is the outermost boundary.

A layer (DGN: level).

Field Type Required Description
color Color yes Default color of entities on this layer.
description string or null no Free-text description.
frozen boolean yes Layer is frozen.
id integer (uint64) or null no Native identifier (DWG handle, DGN level id).
linetype string or null no Default linetype name.
lineweight Lineweight yes Default lineweight.
locked boolean yes Layer is locked.
name string yes Unique name.
plottable boolean yes Layer is plotted.
props map of Value yes Format-specific extras.
visible boolean yes Layer is on / displayed.

Length unit. Mirrors the DWG $INSUNITS set.

Type: "unitless", "inch", "foot", "mile", "millimeter", "centimeter", "meter", "kilometer", "microinch", "mil", "yard", "angstrom", "nanometer", "micrometer", "decimeter", "decameter", "hectometer", "gigameter", "astronomical_unit", "light_year", "parsec", "us_survey_foot" or "custom".

  • "custom": A unit that is not in this list; see Units::meters_per_unit.

A linetype definition.

Field Type Required Description
description string or null no Description text.
name string yes Unique name.
pattern array of number (double) yes Dash pattern in drawing units: positive = dash, negative = gap, zero = dot.
props map of Value yes Format-specific extras.

Line weight.

Tagged by type. Variants:

Use the layer lineweight.

Use the block reference lineweight.

Application default.

Explicit width in millimeters. DGN weight steps are converted; the original goes to props.

Field Type Required Description
value number (double) yes

A space that holds drawn entities: model space, a paper-space layout or a DGN model.

Field Type Required Description
entities array of Entity yes Entities in drawing order.
id integer (uint64) or null no Native identifier.
is_3d boolean yes Model stores 3D geometry.
kind ModelKind yes Kind of space.
name string yes Display name.
props map of Value yes Format-specific extras.

Kind of Model.

Type: "model" or "layout" or "sheet".

  • "model": Design / model space.
  • "layout": Paper-space layout (DWG/DXF).
  • "sheet": Sheet model (DGN).

A 3D point. 2D data uses z = 0 (or the elevation).

Field Type Required Description
x number (double) yes X.
y number (double) yes Y.
z number (double) yes Z.

Original bytes of a record, for lossless inspection.

Field Type Required Description
bytes array of integer (uint8) yes Record bytes exactly as stored (after decompression).
type_code integer (uint32) yes Native type code (DGN element type, DWG object type).

Version of the Document JSON layout, serialized as the integer schema_version. Every document this crate writes carries SchemaVersion::CURRENT. JSON without the field predates versioning and reads as version 1. crate::export::document_from_json rejects other versions with crate::Error::SchemaVersion. The version increases only when an existing field changes meaning or shape; new optional fields do not change it.

Type: integer (uint32).

Origin of a Document.

Field Type Required Description
application string or null no Producing application if recorded, e.g. "MicroStation v8.11.9.578".
codepage string or null no Code page used for 8-bit strings, e.g. "windows-1254".
format Format yes File format family.
version string yes Format version as written in the file, e.g. "AC1032", "V8", "V7".

A text style definition.

Field Type Required Description
font string or null no Font file or font name.
height number (double) yes Fixed text height, 0 when variable.
name string yes Unique name.
oblique number (double) yes Oblique angle in radians.
props map of Value yes Format-specific extras.
width_factor number (double) yes Width factor (1.0 = normal).

Drawing units.

Field Type Required Description
meters_per_unit number (double) or null no Size of one drawing unit in meters, when known. Authoritative over unit for non-standard DGN master units.
unit LengthUnit yes Named unit of the coordinates.

Vertical text alignment.

Type: "baseline", "bottom", "middle", "top".

A loosely typed value for attributes and props.

Type: null or boolean or integer (int64) or number (double) or string or array of Value or array of integer (uint8).

  • null: No value.
  • boolean: Boolean.
  • integer (int64): Integer.
  • number (double): Floating point.
  • string: Text.
  • array of Value: Ordered list.
  • array of integer (uint8): Binary data.

A 3D vector (directions, normals, axes).

Field Type Required Description
x number (double) yes X.
y number (double) yes Y.
z number (double) yes Z.

Polyline vertex.

Field Type Required Description
bulge number (double) yes Bulge of the segment that starts here: tan(included angle / 4), 0 = straight.
end_width number (double) yes End width of the segment that starts here.
position Point3 yes Position.
start_width number (double) yes Start width of the segment that starts here.

A recoverable problem found while reading.

Field Type Required Description
code string yes Stable machine-readable code, e.g. "dgn.unknown_element".
message string yes Human-readable explanation.
object integer (uint64) or null no Native id of the affected object, when known.
offset integer (uint64) or null no Byte offset in the decoded stream, when meaningful.