Structured Data

Ensure data consistency and integrity by validating records against JSON Schema. BlueNexus supports optional schema validation for any collection, allowing you to enforce structure while maintaining flexibility.

Key Features

• JSON Schema Validation: Use standard JSON Schema to define data structure

• Optional Validation: Apply schemas only when needed, on a per-record basis

• Pre-save Verification: Test data against schemas before storing

• Detailed Error Messages: Get specific validation errors to guide corrections

• Flexible Enforcement: Mix validated and unvalidated records in the same collection

What is JSON Schema?

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. It provides a way to:

• Define the structure of your data

• Specify required and optional fields

• Validate data types (string, number, boolean, etc.)

• Enforce constraints (min/max values, string patterns, array lengths)

• Document your data format

Learn more at json-schema.org.

Defining a Schema

Create a JSON Schema document that describes your data structure. Host it at a publicly accessible URL, or use a schema registry service.

Example Schema: Memory Record

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "title": "Memory Record",
  "description": "A user memory or note",
  "required": ["title", "content", "category", "timestamp"],
  "properties": {
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "The title of the memory"
    },
    "content": {
      "type": "string",
      "minLength": 1,
      "description": "The main content of the memory"
    },
    "category": {
      "type": "string",
      "enum": ["work", "personal", "fitness", "health", "other"],
      "description": "Category of the memory"
    },
    "timestamp": {
      "type": "string",
      "format": "date-time",
      "description": "When the memory occurred"
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tags for categorization"
    },
    "mood": {
      "type": "string",
      "description": "User's mood at the time"
    }
  }
}

Hosting Your Schema

Your schema must be accessible via HTTPS. Options include:

• GitHub: Host in a public repository (e.g., https://raw.githubusercontent.com/user/repo/main/schemas/memory.json)

• Cloud Storage: Use AWS S3, Google Cloud Storage, or similar

• CDN: Use a CDN service for better performance

• Your API: Host schemas on your own infrastructure

Verifying Data Against a Schema

Before storing data, you can verify that it conforms to a JSON Schema without actually saving it to the database. This is useful for client-side validation or testing schemas.

import fetch from "node-fetch";

const dataToVerify = {
  schemaUri: "https://example.com/schemas/memory.json",
  title: "Morning Workout",
  content: "Completed 30-minute run",
  category: "fitness",
  timestamp: "2024-12-15T08:30:00Z",
  tags: ["exercise", "health"],
};

const response = await fetch(
  "https://api.bluenexus.ai/api/v1/data/verify",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${USER_ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(dataToVerify),
  }
);

const result = await response.json();

// Example response (valid):
// { "valid": true }

// Example response (invalid):
// {
//   "valid": false,
//   "errors": [
//     { "field": "timestamp", "message": "must be a valid ISO 8601 date string" }
//   ]
// }

See

Writing Data with a Schema

When creating or updating records, include the schemaUri field to validate the data before storing it.

Create with Validation

const memoryData = {
  schemaUri: "https://example.com/schemas/memory.json",
  title: "Morning Workout",
  content: "Completed 30-minute run",
  category: "fitness",
  timestamp: "2024-12-15T08:30:00Z",
  tags: ["exercise", "health"],
  mood: "energized"
};

const response = await fetch(
  "https://api.bluenexus.ai/api/v1/data/memories",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${USER_ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(memoryData),
  }
);

If validation fails, you'll receive a 400 Bad Request response with detailed error information.

See

Update with Validation

const updates = {
  schemaUri: "https://example.com/schemas/memory.json",
  content: "Completed 30-minute run and 15 minutes of stretching",
  tags: ["exercise", "health", "stretching"],
};

const response = await fetch(
  `https://api.bluenexus.ai/api/v1/data/memories/${recordId}`,
  {
    method: "PUT",
    headers: {
      Authorization: `Bearer ${USER_ACCESS_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(updates),
  }
);

See

Schema Validation Behavior

• Optional: schemaUri is optional; records without it are not validated

• Per-record: Each record can use a different schema or no schema at all

• Flexible: You can mix validated and unvalidated records in the same collection

• Enforced on write: Validation happens when creating or updating records

• Immediate feedback: Validation errors are returned immediately with details

Best Practices

• Start simple: Begin with basic schemas and add constraints as needed

• Version your schemas: Use versioned URLs (e.g., schemas/memory-v1.json)

• Document your schemas: Include title and description fields

• Test thoroughly: Use the /verify endpoint to test schemas before deployment

• Handle validation errors: Provide clear feedback to users when validation fails

• Cache schemas: Schema documents are fetched and cached by BlueNexus

• Use references: JSON Schema supports $ref for reusing definitions

• Consider defaults: Define default values in your schema when appropriate

Common Validation Constraints

Constraint	Types	Description
type	All	Data type (string, number, boolean, etc.)
required	object	List of required properties
enum	All	Value must be one of the enumerated values
minLength	string	Minimum string length
maxLength	string	Maximum string length
pattern	string	Must match regex pattern
format	string	Must match format (date-time, email, etc.)
minimum	number	Minimum numeric value
maximum	number	Maximum numeric value
minItems	array	Minimum array length
maxItems	array	Maximum array length
uniqueItems	array	All array items must be unique

See json-schema.org for the full specification.