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.
Versioning
Section titled “Versioning”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.
Getting the JSON
Section titled “Getting the JSON”| 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.
Document
Section titled “Document”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. |
Definitions
Section titled “Definitions”Attachment
Section titled “Attachment”Multi-line text attachment point.
Type: "top_left", "top_center", "top_right", "middle_left", "middle_center", "middle_right", "bottom_left", "bottom_center", "bottom_right".
Attribute
Section titled “Attribute”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. |
AttributeDisplay
Section titled “AttributeDisplay”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:
by_layer
Section titled “by_layer”Use the layer color.
by_block
Section titled “by_block”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. |
DimensionType
Section titled “DimensionType”Dimension kind.
Type: "linear", "aligned", "angular", "angular3_point", "diameter", "radius", "ordinate", "arc_length", "other".
Entity
Section titled “Entity”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. |
EntityKind
Section titled “EntityKind”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. |
polyline
Section titled “polyline”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. |
circle
Section titled “circle”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. |
ellipse
Section titled “ellipse”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). |
spline
Section titled “spline”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). |
m_text
Section titled “m_text”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. |
insert
Section titled “insert”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. |
dimension
Section titled “dimension”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). |
polygon
Section titled “polygon”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. |
leader
Section titled “leader”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. |
viewport
Section titled “viewport”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). |
unknown
Section titled “unknown”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". |
Format
Section titled “Format”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).
GroupKind
Section titled “GroupKind”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.
HAlign
Section titled “HAlign”Horizontal text alignment.
Type: "left", "center", "right", "aligned", "middle", "fit".
HatchEdge
Section titled “HatchEdge”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 |
ellipse
Section titled “ellipse”| 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 |
spline
Section titled “spline”| 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 |
polyline
Section titled “polyline”| Field | Type | Required | Description |
|---|---|---|---|
closed |
boolean | yes | |
vertices |
array of Vertex |
yes |
HatchLoop
Section titled “HatchLoop”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. |
LengthUnit
Section titled “LengthUnit”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; seeUnits::meters_per_unit.
Linetype
Section titled “Linetype”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. |
Lineweight
Section titled “Lineweight”Line weight.
Tagged by type. Variants:
by_layer
Section titled “by_layer”Use the layer lineweight.
by_block
Section titled “by_block”Use the block reference lineweight.
default
Section titled “default”Application default.
millimeters
Section titled “millimeters”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. |
ModelKind
Section titled “ModelKind”Kind of Model.
Type: "model" or "layout" or "sheet".
"model": Design / model space."layout": Paper-space layout (DWG/DXF)."sheet": Sheet model (DGN).
Point3
Section titled “Point3”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). |
SchemaVersion
Section titled “SchemaVersion”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).
SourceInfo
Section titled “SourceInfo”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". |
TextStyle
Section titled “TextStyle”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. |
VAlign
Section titled “VAlign”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. |
Vertex
Section titled “Vertex”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. |
Warning
Section titled “Warning”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. |