Logo
NeoArc Studio

Arguments and Validation

Configure operation arguments with type information, validation constraints, directives, and data lineage tracking.

Arguments define the input parameters for GraphQL operations. The editor supports full argument configuration including type information, validation constraints, directives, and data lineage tracking.

Argument Properties

Type Configuration

Arguments can reference types in two ways:

Nullability and Lists

GraphQL types have explicit nullability. Configure using these properties:

// String (nullable)
{ "typeName": "String", "nullable": true }

// String! (required)
{ "typeName": "String", "nullable": false }

// [String] (nullable list of nullable strings)
{ "typeName": "String", "nullable": true, "isList": true, "listItemNullable": true }

// [String!]! (required list of required strings)
{ "typeName": "String", "nullable": false, "isList": true, "listItemNullable": false }

// [ID!] (nullable list of required IDs)
{ "typeName": "ID", "nullable": true, "isList": true, "listItemNullable": false }

Validation Rules

The validation property defines constraints that the argument must satisfy. NeoArc supports six validation rule types:

Combined Validation

Multiple validation rules can be combined:

{
  "name": "password",
  "typeName": "String",
  "nullable": false,
  "description": "User password meeting security requirements",
  "validation": {
    "minLength": 8,
    "maxLength": 128,
    "pattern": "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d).+$"
  }
}

Argument Directives

Directives can be applied to individual arguments. Common use cases include:

  • @deprecated - Mark argument as deprecated with migration guidance
  • @auth - Field-level authentication requirements
  • @constraint - Custom validation directives
  • @sensitive - Mark arguments containing PII or secrets
{
  "name": "legacyId",
  "typeName": "String",
  "nullable": true,
  "description": "Legacy system identifier",
  "directives": [
    {
      "directiveId": "deprecated",
      "arguments": {
        "reason": "Use 'id' argument instead. Legacy IDs will be removed in v3.0."
      }
    }
  ]
}

Data Lineage

Lineage tracking connects arguments to their source data, enabling traceability from API documentation to underlying data models.

{
  "name": "customerId",
  "typeName": "ID",
  "nullable": false,
  "description": "Unique customer identifier",
  "lineage": {
    "entries": [
      {
        "sourceType": "erd",
        "edrFilePath": "data-architecture/customer-db.erd.json",
        "tableName": "customers",
        "columnName": "customer_id"
      }
    ],
    "notes": "Maps directly to the primary key in the customers table"
  }
}

Lineage supports two source types:

  • ERD - Links to Entity-Relationship Diagram tables and columns
  • Graph - Links to Graph Diagram nodes and properties

Multiple lineage entries can be added when an argument maps to multiple sources.

Default Values

Arguments can have default values that apply when the argument is omitted:

// String default
{ "name": "sort", "typeName": "String", "defaultValue": "createdAt" }

// Numeric default
{ "name": "limit", "typeName": "Int", "defaultValue": "20" }

// Boolean default
{ "name": "includeDeleted", "typeName": "Boolean", "defaultValue": "false" }

// Enum default
{ "name": "order", "typeName": "SortOrder", "defaultValue": "DESC" }

Complete Argument Example

{
  "id": "arg-search-query",
  "name": "query",
  "typeName": "String",
  "nullable": false,
  "description": "Search query string. Supports full-text search with AND, OR, and NOT operators.",
  "validation": {
    "minLength": 2,
    "maxLength": 500
  },
  "lineage": {
    "entries": [
      {
        "sourceType": "graph",
        "graphFilePath": "knowledge-graph/search-index.diagram.json",
        "nodeId": "node-search-terms",
        "nodeName": "SearchTerms",
        "propertyName": "queryText"
      }
    ],
    "notes": "Indexed in Elasticsearch for full-text search"
  },
  "directives": [
    {
      "directiveId": "sensitive",
      "arguments": {
        "reason": "May contain PII in search queries"
      }
    }
  ]
}

Related Content