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

# JSON Schemas

> Example JSON schemas for common use cases

The `schema` parameter defines the structure of your response data. It must be a valid [JSON Schema](https://json-schema.org/).

## Basic Schemas

<AccordionGroup>
  <Accordion title="Simple Array of Companies" icon="building">
    Basic company information in an array format.

    ```json theme={null}
    {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": { "type": "string" },
          "domain": { "type": "string" },
          "description": { "type": "string" }
        }
      }
    }
    ```

    **Example output:**

    ```json theme={null}
    [
      {
        "name": "Example Corp",
        "domain": "example.com",
        "description": "A technology company"
      }
    ]
    ```
  </Accordion>

  <Accordion title="Single Company Object" icon="building">
    Single company information as an object.

    ```json theme={null}
    {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "domain": { "type": "string" },
        "founded_year": { "type": "number" },
        "headquarters": { "type": "string" },
        "industry": { "type": "string" }
      }
    }
    ```

    **Example output:**

    ```json theme={null}
    {
      "name": "Example Corp",
      "domain": "example.com",
      "founded_year": 2020,
      "headquarters": "San Francisco, CA",
      "industry": "Technology"
    }
    ```
  </Accordion>
</AccordionGroup>

## Contact Information

<AccordionGroup>
  <Accordion title="Companies with Executive Contacts" icon="user-tie">
    Company data enriched with CEO contact information.

    ```json theme={null}
    {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "company_name": { "type": "string" },
          "domain": { "type": "string" },
          "ceo_name": { "type": "string" },
          "ceo_email": { "type": "string", "format": "email" },
          "ceo_linkedin": { "type": "string", "format": "uri" },
          "ceo_phone": { "type": "string" }
        },
        "required": ["company_name", "domain"]
      }
    }
    ```
  </Accordion>

  <Accordion title="Full Contact Information" icon="address-book">
    Detailed contact information with multiple fields.

    ```json theme={null}
    {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "company": { "type": "string" },
          "contact_name": { "type": "string" },
          "title": { "type": "string" },
          "email": { "type": "string", "format": "email" },
          "phone": { "type": "string" },
          "linkedin": { "type": "string", "format": "uri" },
          "twitter": { "type": "string" }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Financial Data

<AccordionGroup>
  <Accordion title="Company Financials" icon="chart-line">
    Financial metrics and funding information.

    ```json theme={null}
    {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "company_name": { "type": "string" },
          "revenue": { "type": "string" },
          "employees": { "type": "number" },
          "funding_stage": { "type": "string" },
          "total_funding": { "type": "string" },
          "last_funding_date": { "type": "string" },
          "valuation": { "type": "string" }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Investment Data" icon="sack-dollar">
    Investor and funding round information.

    ```json theme={null}
    {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "company_name": { "type": "string" },
          "round_type": { "type": "string" },
          "amount_raised": { "type": "string" },
          "date": { "type": "string" },
          "lead_investor": { "type": "string" },
          "participating_investors": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Industry-Specific

<AccordionGroup>
  <Accordion title="SaaS Companies" icon="cloud">
    Schema optimized for SaaS company data.

    ```json theme={null}
    {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "company_name": { "type": "string" },
          "domain": { "type": "string" },
          "product_name": { "type": "string" },
          "product_category": { "type": "string" },
          "pricing_model": { "type": "string" },
          "target_market": { "type": "string" },
          "integrations": {
            "type": "array",
            "items": { "type": "string" }
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="E-commerce Brands" icon="cart-shopping">
    Schema for e-commerce and retail companies.

    ```json theme={null}
    {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "brand_name": { "type": "string" },
          "website": { "type": "string" },
          "product_categories": {
            "type": "array",
            "items": { "type": "string" }
          },
          "marketplaces": {
            "type": "array",
            "items": { "type": "string" }
          },
          "annual_revenue": { "type": "string" },
          "headquarters": { "type": "string" }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Healthcare Providers" icon="hospital">
    Schema for healthcare and medical organizations.

    ```json theme={null}
    {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "facility_name": { "type": "string" },
          "facility_type": { "type": "string" },
          "address": { "type": "string" },
          "specialties": {
            "type": "array",
            "items": { "type": "string" }
          },
          "bed_count": { "type": "number" },
          "accreditation": { "type": "string" }
        }
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Complex Structures

<AccordionGroup>
  <Accordion title="Nested Company Data" icon="sitemap">
    Complex nested structure with multiple levels.

    ```json theme={null}
    {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "company": {
            "type": "object",
            "properties": {
              "name": { "type": "string" },
              "domain": { "type": "string" },
              "description": { "type": "string" }
            }
          },
          "leadership": {
            "type": "object",
            "properties": {
              "ceo": { "type": "string" },
              "cto": { "type": "string" },
              "cfo": { "type": "string" }
            }
          },
          "metrics": {
            "type": "object",
            "properties": {
              "employees": { "type": "number" },
              "revenue": { "type": "string" },
              "growth_rate": { "type": "string" }
            }
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="With Required Fields" icon="asterisk">
    Schema with required and optional fields.

    ```json theme={null}
    {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "company_name": { "type": "string" },
          "domain": { "type": "string" },
          "industry": { "type": "string" },
          "founded_year": { "type": "number" },
          "description": { "type": "string" }
        },
        "required": ["company_name", "domain"],
        "additionalProperties": false
      }
    }
    ```

    <Note>
      Fields listed in `required` must be present in the response. Optional fields may be omitted if data is unavailable.
    </Note>
  </Accordion>
</AccordionGroup>

## Field Types Reference

<Tabs>
  <Tab title="String">
    Text data of any length.

    ```json theme={null}
    {
      "field_name": { "type": "string" }
    }
    ```

    **With format:**

    ```json theme={null}
    {
      "email": { "type": "string", "format": "email" },
      "url": { "type": "string", "format": "uri" },
      "date": { "type": "string", "format": "date" }
    }
    ```
  </Tab>

  <Tab title="Number">
    Numeric data (integers or decimals).

    ```json theme={null}
    {
      "employees": { "type": "number" },
      "revenue": { "type": "number" }
    }
    ```

    **With constraints:**

    ```json theme={null}
    {
      "age": {
        "type": "number",
        "minimum": 0,
        "maximum": 150
      }
    }
    ```
  </Tab>

  <Tab title="Boolean">
    True/false values.

    ```json theme={null}
    {
      "is_public": { "type": "boolean" },
      "has_funding": { "type": "boolean" }
    }
    ```
  </Tab>

  <Tab title="Array">
    Lists of values.

    ```json theme={null}
    {
      "tags": {
        "type": "array",
        "items": { "type": "string" }
      }
    }
    ```

    **Array of objects:**

    ```json theme={null}
    {
      "employees": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "name": { "type": "string" },
            "role": { "type": "string" }
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Object">
    Nested data structures.

    ```json theme={null}
    {
      "address": {
        "type": "object",
        "properties": {
          "street": { "type": "string" },
          "city": { "type": "string" },
          "country": { "type": "string" }
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Best Practices

<CardGroup cols={2}>
  <Card title="Be Specific" icon="bullseye">
    Define clear property names that match the data you're requesting
  </Card>

  <Card title="Use Formats" icon="check">
    Specify formats for emails, URLs, dates to ensure proper validation
  </Card>

  <Card title="Mark Required Fields" icon="asterisk">
    Use `required` array to specify which fields must be present
  </Card>

  <Card title="Keep It Simple" icon="shapes">
    Start with simple schemas and add complexity as needed
  </Card>
</CardGroup>

## Tips for Better Results

<Steps>
  <Step title="Match Query to Schema">
    Ensure your natural language query asks for the same fields defined in your schema
  </Step>

  <Step title="Use Descriptive Names">
    Use clear, descriptive property names like `ceo_email` instead of `e`
  </Step>

  <Step title="Test Incrementally">
    Start with a few fields and gradually add more to your schema
  </Step>

  <Step title="Review Responses">
    Check the `raw` field in responses to understand how the AI interpreted your query
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Query" icon="plus" href="/api-reference/create-query">
    Use these schemas in your API queries
  </Card>

  <Card title="Quick Start" icon="rocket" href="/quickstart">
    See complete examples with schemas
  </Card>
</CardGroup>