Structures

This section covers complex data structures in dotjson: objects and arrays. These structures allow you to model hierarchical and collection-based data.

Objects

Objects are key-value pairs that represent structured data. They’re the foundation of most JSON schemas.

Basic Object Structure

{
  "type": "object",
  "properties": {
    "firstName": { "type": "string" },
    "lastName": { "type": "string" },
    "age": { "type": "integer" }
  }
}

{
  "firstName": "John",
  "lastName": "Doe",
  "age": 30
}

Required Properties

By default, object properties are optional. Use the required array to specify mandatory fields:

{
  "type": "object",
  "properties": {
    "id": { "type": "string" },
    "name": { "type": "string" },
    "email": { "type": "string" },
    "phone": { "type": "string" },
    "address": { "type": "string" }
  },
  "required": ["id", "name", "email"]
}

Minimal valid object:

{
  "id": "user123",
  "name": "Jane Smith",
  "email": "[email protected]"
}

With optional fields:

{
  "id": "user123",
  "name": "Jane Smith",
  "email": "[email protected]",
  "phone": "+1-555-1234",
  "address": "123 Main St"
}

Nested Objects

Objects can contain other objects, creating hierarchical structures:

{
  "type": "object",
  "properties": {
    "username": { "type": "string" },
    "profile": {
      "type": "object",
      "properties": {
        "firstName": { "type": "string" },
        "lastName": { "type": "string" },
        "bio": { "type": "string" }
      },
      "required": ["firstName", "lastName"]
    },
    "settings": {
      "type": "object",
      "properties": {
        "theme": { "type": "string" },
        "notifications": { "type": "boolean" },
        "language": { "type": "string" }
      },
      "required": ["theme", "notifications"]
    }
  },
  "required": ["username", "profile"]
}

{
  "username": "johndoe",
  "profile": {
    "firstName": "John",
    "lastName": "Doe",
    "bio": "Software developer and tech enthusiast"
  },
  "settings": {
    "theme": "dark",
    "notifications": true,
    "language": "en"
  }
}

Deeply Nested Structures

You can nest objects to any depth to model complex relationships:

{
  "type": "object",
  "properties": {
    "company": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "address": {
          "type": "object",
          "properties": {
            "street": { "type": "string" },
            "city": { "type": "string" },
            "state": { "type": "string" },
            "postalCode": { "type": "string" },
            "country": { "type": "string" }
          },
          "required": ["street", "city", "country"]
        },
        "contact": {
          "type": "object",
          "properties": {
            "primary": {
              "type": "object",
              "properties": {
                "name": { "type": "string" },
                "email": { "type": "string" },
                "phone": { "type": "string" }
              },
              "required": ["name", "email"]
            }
          },
          "required": ["primary"]
        }
      },
      "required": ["name", "address", "contact"]
    }
  },
  "required": ["company"]
}

{
  "company": {
    "name": "Tech Corp",
    "address": {
      "street": "100 Innovation Way",
      "city": "San Francisco",
      "state": "CA",
      "postalCode": "94105",
      "country": "USA"
    },
    "contact": {
      "primary": {
        "name": "Alice Johnson",
        "email": "[email protected]",
        "phone": "+1-555-0100"
      }
    }
  }
}

Important

Additional Properties: By default, additionalProperties is set to false in dotjson, meaning objects cannot contain properties not defined in the schema. Setting it to true is not currently supported.

Arrays

Arrays represent ordered collections of items. They can contain elements of the same type or mixed types.

Basic Arrays with `items`

Use the items keyword to define arrays where all elements share the same schema:

{
  "type": "object",
  "properties": {
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "description": "List of tags"
    },
    "scores": {
      "type": "array",
      "items": { "type": "number" },
      "description": "List of scores"
    }
  },
  "required": ["tags", "scores"]
}

{
  "tags": ["javascript", "web", "frontend"],
  "scores": [85.5, 92.0, 78.3, 88.7]
}

Array Length Constraints

Control array size with minItems and maxItems:

{
  "type": "object",
  "properties": {
    "topThree": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1,
      "maxItems": 3,
      "description": "Top three choices"
    },
    "requiredList": {
      "type": "array",
      "items": { "type": "integer" },
      "minItems": 5,
      "description": "At least 5 items required"
    }
  },
  "required": ["topThree", "requiredList"]
}

{
  "topThree": ["Gold", "Silver", "Bronze"],
  "requiredList": [10, 20, 30, 40, 50, 60]
}

Arrays of Objects

Arrays commonly contain objects for representing collections of structured data:

{
  "type": "object",
  "properties": {
    "users": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": { "type": "integer" },
          "name": { "type": "string" },
          "email": { "type": "string" },
          "role": { "type": "string" },
          "active": { "type": "boolean" }
        },
        "required": ["id", "name", "email", "role"]
      },
      "minItems": 1,
      "description": "List of users"
    }
  },
  "required": ["users"]
}

{
  "users": [
    {
      "id": 1,
      "name": "Alice Johnson",
      "email": "[email protected]",
      "role": "admin",
      "active": true
    },
    {
      "id": 2,
      "name": "Bob Smith",
      "email": "[email protected]",
      "role": "user",
      "active": true
    },
    {
      "id": 3,
      "name": "Charlie Brown",
      "email": "[email protected]",
      "role": "viewer",
      "active": false
    }
  ]
}

Tuples with `prefixItems`

Use prefixItems to define heterogeneous arrays (tuples):

{
  "type": "object",
  "properties": {
    "point": {
      "type": "array",
      "prefixItems": [
        { "type": "number" },
        { "type": "number" }
      ]
    }
  }
}

{
  "point": [12.5, 8.0]
}

Next Steps

Learn about Constraints for advanced options.
Explore Composition for schema reuse and complex patterns.
See Practical Examples for real-world applications.

Data Types Constraints