Schema Import (for AI agents)¶

Apilane can bulk-import entities, properties, constraints, security rules and custom endpoints into an existing application from a single JSON document. This page is a precise specification of that JSON so an AI agent (or any automation) can generate a valid payload from scratch.

Open it in the Portal at Application → Import, paste the JSON into the JSON payload box, and click Import. (The same page can also pre-fill the payload by diffing another application — the Load from another application panel — which is a good way to see a real payload.)

How the import behaves¶

• Additive and idempotent. The import only ever creates what is missing. Existing entities, properties, constraints, security rules and custom endpoints are never modified or deleted.
• Existing items are validated, not overwritten. If an entity/property/security rule already exists, its metadata is compared against the payload. If it is identical, it is skipped (a warning is returned). If it differs, the whole import aborts with an error — nothing is half-applied for that mismatch.
• FK-dependency ordering is automatic. Entities are created in foreign-key dependency order, so you may list them in any order — a child entity may appear before the parent it references, as long as both are in the payload (or the parent already exists).
• System columns are added for you. When a new entity is created, Apilane automatically adds its system properties (ID, Owner, Created, …). Never include them in Properties.

Top-level shape¶

{
  "Entities": [],
  "Security": [],
  "CustomEndpoints": []
}

All three arrays are optional — include only what you want to import.

Entities¶

{
  "Name": "Product",
  "Description": "Product catalog",
  "RequireChangeTracking": false,
  "HasDifferentiationProperty": false,
  "Properties": [],
  "Constraints": []
}

Properties¶

{
  "Name": "Price",
  "TypeID": 2,
  "Required": true,
  "Minimum": 0,
  "Maximum": null,
  "DecimalPlaces": 2,
  "Encrypted": false,
  "ValidationRegex": null,
  "Description": null
}

TypeID values (PropertyType):

Constraints¶

A constraint is { "TypeID": <int>, "Properties": "<string>" }. The Properties string is encoded differently per type.

For a foreign key, first add a Number property to hold the reference (e.g. Product_ID), then add the FK constraint pointing at the referenced entity's name. The FK targets that entity's ID primary key.

On-delete logic (ForeignKeyLogic, the optional 3rd element; defaults to 0):

Security rules¶

Each entry is a DBWS_Security rule granting a role permission to perform an action on an entity, custom endpoint, or the schema.

{
  "Name": "Product",
  "TypeID": 0,
  "RoleID": "ANONYMOUS",
  "Action": "get",
  "Record": 0,
  "Properties": null,
  "RateLimit": null
}

TypeID values (SecurityTypes):

Record values (EndpointRecordAuthorization):

Roles. Apilane always evaluates a user's custom roles plus the two built-ins:

Rate limit (optional)¶

"RateLimit": { "MaxRequests": 100, "TimeWindowType": 2 }

Custom endpoints¶

{
  "Name": "GetAllProduct",
  "Description": "Retrieves all products.",
  "Query": "SELECT * FROM [Product];"
}

See Custom Endpoints for query authoring details. Importing a custom endpoint does not create a security rule for it — add a matching Security entry with TypeID: 1 to expose it.

Complete example¶

Creates a Product and OrderItem (with a foreign key to Product), makes Product readable by anonymous users, and adds a custom endpoint:

{
  "Entities": [
    {
      "Name": "Product",
      "Description": "Product catalog",
      "RequireChangeTracking": false,
      "HasDifferentiationProperty": false,
      "Properties": [
        { "Name": "Title", "TypeID": 1, "Required": true,  "Minimum": null, "Maximum": 200,  "DecimalPlaces": null, "Encrypted": false, "ValidationRegex": null, "Description": null },
        { "Name": "Price", "TypeID": 2, "Required": true,  "Minimum": 0,    "Maximum": null, "DecimalPlaces": 2,    "Encrypted": false, "ValidationRegex": null, "Description": null }
      ],
      "Constraints": [
        { "TypeID": 1, "Properties": "Title" }
      ]
    },
    {
      "Name": "OrderItem",
      "Description": "Line item in an order",
      "RequireChangeTracking": false,
      "HasDifferentiationProperty": false,
      "Properties": [
        { "Name": "Product_ID", "TypeID": 2, "Required": true, "Minimum": null, "Maximum": null, "DecimalPlaces": 0, "Encrypted": false, "ValidationRegex": null, "Description": null },
        { "Name": "Qty",        "TypeID": 2, "Required": true, "Minimum": 1,    "Maximum": null, "DecimalPlaces": 0, "Encrypted": false, "ValidationRegex": null, "Description": null }
      ],
      "Constraints": [
        { "TypeID": 2, "Properties": "Product_ID,Product,2" }
      ]
    }
  ],
  "Security": [
    { "Name": "Product", "TypeID": 0, "RoleID": "ANONYMOUS", "Action": "get", "Record": 0, "Properties": "Title,Price", "RateLimit": { "MaxRequests": 100, "TimeWindowType": 2 } }
  ],
  "CustomEndpoints": [
    { "Name": "GetAllProduct", "Description": "Retrieves all products.", "Query": "SELECT * FROM [Product];" }
  ]
}

Checklist for generating a payload¶

• [ ] Use the correct integer enums: property TypeID (String=1, Number=2, Boolean=3, Date=4); constraint TypeID (Unique=1, FK=2); security TypeID (Entity=0, CustomEndpoint=1, Schema=2).
• [ ] Do not include system properties (ID, Owner, Created) — they are added automatically.
• [ ] Foreign keys: add a Number property to hold the reference, then a constraint "LocalColumn,ReferencedEntity[,OnDeleteLogic]".
• [ ] DecimalPlaces only for Number; Encrypted/ValidationRegex only for String; Minimum/Maximum mean length for strings and value for numbers/dates.
• [ ] Every entity referenced by an FK must be in the payload or already exist in the target app.
• [ ] To expose a custom endpoint, add a Security rule with TypeID: 1 and Action: "get".
• [ ] Grant columns explicitly in each security rule's Properties — a null grants no non-PK columns.
• [ ] For existing items, keep metadata identical to what is already in the app, or the import aborts. ```