Technical Specification

Technical overview of the current data-driven REST contract and the GraphQL adapter and composition layer above it. This sheet documents the available CRUD core, the GraphQL capabilities, and the limits of each runtime.

Implementation Status

Component	Status	Scope
Relational metamodel	Implemented	Structured databases, schemas, tables, columns, and relationships
Visual modeling	Implemented	Artificial Interface Studio
OpenAPI generation	Implemented	OpenAPI/Swagger documentation from the data model
Swagger UI and Mermaid ERD	Implemented	Visualizes the contract and relational structure
Contract export	Implemented	Download and handoff to your own Git/CI/CD processes
REST runtime	In development	Separate project for executing the data-driven contract
GraphQL runtime	In development	Dynamic adapter and composition layer over the Swagger-based REST interface
MCP integration	In development	Structured access for AI agents
Contract diff, policies, SDKs, mock servers, and contract tests	Planned / not presented as finished	No completed product promises

Validation Scope

Current Studio validation checks, among other things:

missing and duplicate names for databases, schemas, tables, and columns,
empty tables and missing or invalid data types,
invalid length and numeric ranges,
complete and existing references to a schema, table, and column,
different reference types as a warning and missing id columns as a warning.

This does not currently mean automatic breaking-change analysis, organization-specific policies, security governance, or a general guarantee of production readiness.

Boundary Between Data Model and API

The current implementation is deliberately data-driven: relational schemas, tables, and columns are mapped closely to CRUD resources. The OpenAPI extensions x-database-schema and x-database-table make that mapping explicit.

Relational model
        ↓ current mapping
OpenAPI CRUD contract
        ↓
REST runtime
        ↓
GraphQL adapter and composition layer

Artificial Interface should therefore be understood today as a controlled Database-to-CRUD Contract layer. Independent domain resources, composed API resources, computed fields, and commands are possible extensions, but are not current promises of this specification.

REST Specifications

Name	Data-Driven REST API
API Type	RESTful CRUD API
Project Status	Actively evolving; specific production environments require their own security, operations, and performance review
Specification Standard	OpenAPI 2.0 / Swagger 2.0, OpenAPI 3.0
Data Format	JSON
Authentication	Flexibly configurable; for example, API key, bearer auth, or custom authentication methods
Example Authentication Headers	`x-api-key`, `Authorization: Bearer <token>`
Content-Type	`application/json`
Endpoint Pattern	`/schema_name/entity`
Single Resource	`/schema_name/entity/{id}`
Supported HTTP Methods	`GET`, `POST`, `PATCH`, `DELETE`
GET Function	Retrieve, filter, sort, and paginate entities
POST Function	Create one or more entities
PATCH Function	Partially update one or more entities
DELETE Function	Delete one or more entities by ID
Batch Processing	Supported for `POST` and `PATCH` through JSON arrays
Transactional Processing	Versioned ordered REST workflows with RFC 6901 bindings and atomic commit/rollback; nested GraphQL writes use the same workflow internally
Filtering	Exact filters, multiple values, date ranges, LIKE searches, and combined filters
Horizontal Filtering	Through `$select`
Sorting	Through `$orderBy`
Pagination	Through `$limit` and `$offsetId`
Multiple Query Parameter Values	Pipe-delimited, for example `id=1\|2\|3`
Date Format	ZULU/ISO time format, for example `2023-01-01T00:00:00Z`
LIKE Wildcards	`%` for any character sequence, `_` for a single character
Database Mapping	Relational database structures with schemas, tables, fields, and relationships
OpenAPI Extensions	`x-swagger-router-controller`, `x-database-schema`, `x-database-table`
Controller Model	Generic controller, for example, `GenericController`
Default Success Status	`200 OK`
Error Status Codes	`400 Bad Request`, `401 Unauthorized`, `500 Internal Server Error`
Schema Support	Data types, required fields, constraints, unique values, and relationships
Client Compatibility	Suitable for OpenAPI/Swagger-based client generation
Documentation Compatibility	Suitable for Swagger UI and OpenAPI-compatible tools
Primary Purpose	Standardized API layer for managing relational data through CRUD operations
Typical Use Cases	CRUD backends, data-driven applications, internal enterprise APIs, and API-first development
Current Building Blocks	Visual data modeling, OpenAPI generation, Swagger UI, Mermaid ERD, data-driven REST runtime, GraphQL adapter and composition layer, and MCP access
Automation Options	OpenAPI contract export and CI/CD integration; further targets such as clients, SDKs, mock servers, and contract tests are not presented as completed product features
Technical Focus	Reproducible model-to-contract transformation with explicit mapping to relational structures and standardized CRUD operations

GraphQL Runtime

The GraphQL runtime is a dynamically generated adapter and composition layer over the REST runtime. It has no data store of its own: the REST API remains the operational interface for data access and CRUD operations.

GraphQL client
        ↓
GraphQL runtime
  schema generation · translation · relationship resolution · batching
        ↓
REST runtime
        ↓
Database

Schema Source	Swagger-2-style API contract with `definitions`, `paths`, and relational extensions
Queries	Dynamic GraphQL fields for defined `*.get` operations
Mutations	`POST`, `PATCH`, and supported `DELETE` paths; batched data is supported
Field Selection	Translates selected GraphQL fields into REST `$select` parameters
Query Arguments	List-based field filters, `_orderBy`, and `_limit` with `offset` and `amount`
Relationships	Forward and reverse relationships with multiple nesting levels from `x-relation-*` metadata
Batching	Request-scoped DataLoaders deduplicate IDs and batch relationship queries to the REST API
Nested Mutations	Related records are created in sequence or updated when an existing ID is provided
Type Safety	GraphQL validates field names, arguments, and data types; standard introspection is supported
Authentication	`Authorization` and `x-api-key` are forwarded; authorization is not implemented by this runtime itself

Current Limits

/transaction is not exposed as a GraphQL mutation.
The REST parameters $filter and $offsetId are not official GraphQL arguments.
Automatic mapping focuses on database-oriented CRUD resources, not arbitrary domain commands or freely defined endpoints.
Typed nested POST/PATCH mutations are compiled into one ordered REST /transaction workflow and execute atomically; direct REST CRUD calls remain available independently.
General native OpenAPI 3 processing is not assumed; the runtime currently expects a Swagger-2-style structure.
Delete paths used for schema generation should currently use the /{id} spelling.

Source

This sheet refers to the current Artificial Interface building blocks: the data and API model, the Studio, OpenAPI generation, the REST/GraphQL runtime, and MCP access. Detailed endpoint semantics are described in the API documentation.