> ## Documentation Index
> Fetch the complete documentation index at: https://atlos.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Guide: JSON Schema

> Learn how to build a schema for your unstructured data

Atlos uses a sub-set of the [JSON schema](https://json-schema.org/) to extract data from unstructured data.

## Basics

A JSON schema is made up of `Fields`.

A field has the following components:

* `name`: The name of the field
* `type`: The type of the field
* `description`: A description of the field

⚠️ Important: Only these three components are supported. Additional components will fail.

### Field Types

* `string`: Text data like names, addresses, and emails
* `integer`: Whole numbers like page count or household size
* `number`: Decimal numbers like prices or measurements
* `boolean`: True or False
* `enum`: List of predefined values like colors or sizes
* `array`: List of items of the same type
* `object`: Groups related data together

## Best Practices

### Naming

* Provide specific field names, e.g prefer `full_name` over `name`
* Use consistent naming convention such as `snake_case`.

### Utilize Enums

Enums should always be used when there is a known set of possible values.

For example, prefer:

```json
{
  "type": "object",
  "properties": {
    "shipping_status": {
      "type": "enum",
      "enum": ["pending", "shipped", "delivered", "cancelled"]
    }
  },
  "required": ["shipping_status"]
}
```

Over just using a `string` type:

```json
{
  "type": "object",
  "properties": {
    "shipping_status": {
      "type": "string"
    }
  }
}
```

### Specify Required Fields

* Make use of the `required` property to specify which fields are needed so that data is extracted correctly.

## Example Schemas

### Simple

A simple schema which extracts the required first and last name values from a document.

```json
{
  "type": "object",
  "properties": {
    "first_name": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    }
  },
  "required": ["first_name", "last_name"]
}
```

### Enums

A schema which extracts the the shipping status of an order.

```json
{
  "type": "object",
  "properties": {
    "shipping_status": {
      "type": "enum",
      "enum": ["pending", "shipped", "delivered", "cancelled"]
    }
  },
  "required": ["shipping_status"]
}
```

### Objects & Arrays

An object schema which extracts data about a `Person`. Take note of the nested `address` object.

```json
{
  "type": "object",
  "properties": {
    "first_name": {
      "type": "string"
    },
    "last_name": {
      "type": "string"
    },
    "age": {
      "type": "integer"
    },
    "hobbies": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "address": {
      "type": "object",
      "properties": {
        "street": {
          "type": "string"
        },
        "city": {
          "type": "string"
        },
        "state": {
          "type": "string"
        },
        "zip": {
          "type": "string"
        }
      },
      "required": ["street", "city", "state", "zip"]
    }
  },
  "required": ["first_name", "last_name", "age", "address"]
}
```

Schemas can be generated within our [Playground](https://www.atlos.dev/playground), or programmatically using our API.

## Something missing?

If you need help with something that is not covered in the documentation, please let us know by sending a message to `alex@atlos.dev`