Infrastructure Description Format (IDF)

Infrastructure Description Format is a flat JSON or CSV representation of components, groups, connections, frames and images. Arcentry turns IDF into a semantically arranged diagram: it assigns tiers, lays out nested groups, routes connections and then adds explicitly positioned content.

Use IDF to visualize existing environments, document deployments, generate diagrams from infrastructure templates or keep a generated diagram synchronized with another source of truth.

Create or replace a diagram

Send IDF with an HTTP POST request to https://arcentry.com/api/v1/create-diagram/<docId>. The document must already exist and belong to the organization associated with the API key. Authenticate as described in Getting Started and set Content-Type to application/json or text/csv.

Important: this endpoint replaces the document's complete content. Existing components, connections, labels, images and other objects in the target document are removed. Create or clone a document first if the existing content must be preserved.

curl \
--data-binary "@architecture.csv" \
-H "Authorization: Bearer <api-key>" \
-H "Content-Type: text/csv" \
-X POST \
https://arcentry.com/api/v1/create-diagram/25f2ff32-ccb3-3425-a86e-66c6c6b92a1c

curl \
--data '{"server-a":{"type":"component","componentType":"generic.server"}}' \
-H "Authorization: Bearer <api-key>" \
-H "Content-Type: application/json" \
-X POST \
https://arcentry.com/api/v1/create-diagram/25f2ff32-ccb3-3425-a86e-66c6c6b92a1c

A successful request returns HTTP 200. Common failures are:

JSON and CSV representation

In JSON, the top-level value is an object whose keys are entry IDs. Do not add a separate id property; the top-level key is authoritative. In CSV, every row is an entry and the id column is required. IDs must be unique. Duplicate CSV IDs are rejected.

{
  "server-a": {
    "type": "component",
    "componentType": "generic.server",
    "groups": ["region-a", "subnet-a"],
    "connections": ["database-a"]
  },
  "database-a": {
    "type": "component",
    "componentType": "database.postgres",
    "groups": ["region-a", "subnet-a"]
  }
}

JSON list properties are arrays of strings. In CSV, use a comma-separated value inside a quoted cell for groups, connections, frames and list-valued arrowsTo. Empty CSV cells are omitted. Values in these list columns remain string IDs, including numeric-looking IDs. In other columns, case-insensitive true and false become booleans and numeric cells become numbers. Quote values that contain commas. Numeric-looking text such as 00123 is converted to the number 123, so add a non-numeric prefix if leading zeroes are significant.

Entry types

Every entry has one of five types:

• component: a cloud, infrastructure or generic diagram component.
• group: a nested area around components or other groups.
• connection: settings and optional content for one connection.
• frame: a cross-cutting area around components or groups outside the group hierarchy.
• image: a standalone image positioned at an absolute coordinate or relative to a component or group.

See the complete IDF property reference for every supported property and default.

Components

Components are the main diagram objects. In addition to type: "component", each requires a componentType containing exactly one category and component name, for example generic.server or database.postgres. In the application, place and select a component and inspect its object data to find its component ID.

Connections and arrows

Add a connections list to a component or group. Each value is the ID of another component or group. Define each undirected connection only once; reciprocal entries are deduplicated. arrowsTo can be all or a list of connection target IDs and adds an arrow at those targets.

For line styling, direction-specific arrowheads, a line label or a component placed on a connection, add a standalone connection entry. Its from and to properties establish the connection, so it does not also have to be listed in connections.

{
  "database-link": {
    "type": "connection",
    "from": "server-a",
    "to": "database-a",
    "arrowEnd": true,
    "lineColor": "#0000FF",
    "lineDash": "dotted",
    "label": "SQL"
  }
}

Groups and nesting

A component or group can list the groups it belongs to. Order the list from outermost parent to innermost child. Group IDs can be inferred from membership lists; add an explicit group entry when the group needs a label, styling, connections, a tier, ordering or frame membership.

Use the same parent-to-child ordering everywhere a hierarchy appears. An entry cannot contain itself or repeat the same group. Components that have no groups are placed in an automatically generated default group.

Tiers and ordering

Tiers place components in horizontal rows, ordered from front to back. Without an explicit tier, Arcentry uses the component category. The current category mapping is:

• Tier 6

  ai, analytics, storage

• Tier 5

  database

• Tier 4

  data-processing, monitoring, devops

• Tier 3

  media, messaging

• Tier 2

  container, computation, cache

• Tier 1

  security, API, gaming, networking

• Tier 0

  IoT and selected client-device generic components

Set numeric tier on a component to override categorization. A tier on an explicit group is inherited by its contained components unless a component supplies its own tier. Use numeric order to arrange components within a group/tier or sibling groups within their tier; lower values come first.

Automatic, absolute and relative positioning

Components default to positionType: "auto". Set absolute with numeric positionX and positionY to place a component directly. Set relative to offset it from an explicitly defined component or non-empty group. Relative positioning also requires positionRelativeTo. For a group target, positionPointX selects left/middle/right and positionPointY selects top/middle/bottom; both default to middle.

{
  "region-icon": {
    "type": "component",
    "componentType": "generic.image",
    "positionType": "relative",
    "positionRelativeTo": "region-a",
    "positionPointX": "left",
    "positionPointY": "top",
    "positionX": 0.5,
    "positionY": 0.5
  }
}

Frames

Frames draw a shared outline around components or groups without changing their group hierarchy. Add frame IDs to a component's or group's frames list. A frame is created implicitly from those memberships; add a frame entry to configure its label, colors, line style, shape or per-side padding. One item can belong to multiple frames. Overlapping rectangular frames may be changed to irregular outlines automatically so they can tile around one another.

{
  "server-a": {
    "type": "component",
    "componentType": "generic.server",
    "frames": ["availability-zone-a"]
  },
  "availability-zone-a": {
    "type": "frame",
    "label": "Availability Zone A",
    "lineDash": "dashed",
    "paddingLeft": 0.5,
    "paddingRight": 0.5
  }
}

Standalone images

An image entry creates a standalone image object. It is different from a generic.image component: standalone images do not participate in automatic tiers, groups or connection routing. Supply path, numeric positionX and positionY, plus optional width, height, rotation and stretch settings. Images support the same absolute and relative coordinate rules as components.

{
  "logo": {
    "type": "image",
    "path": "/uploaded-images/company-logo.png",
    "positionType": "relative",
    "positionRelativeTo": "region-a",
    "positionPointX": "right",
    "positionPointY": "top",
    "positionX": -1,
    "positionY": 1,
    "width": 3,
    "height": 2,
    "stretchToSize": false
  }
}

Labels and styling

Components, groups, frames and connections support labels. Group labels default to the block style; choose inline for a label attached to a border. Most normal Arcentry object properties can be included directly in component, group and frame entries. See the object property reference and the IDF reference for supported IDF-specific behavior.

Metadata

Prefix component keys or CSV columns with meta-; the prefix is removed when the diagram object is created. JSON can alternatively use a meta object. Use showMetaData, showOnCanvas, showInTooltip and the metadata typography properties to control presentation. See Metadata for interaction and search behavior.

Layout settings

Query parameters control component gaps, group margins and padding, label geometry and tier wrapping. See IDF automatic layout settings for the complete, current list and defaults.