🔍 Location Schemas

Location schemas provide JSON Schema definitions for location data validation in NodeBlocks applications. These schemas ensure data integrity and provide clear contracts for location-related API endpoints.

---

🎯 Overview

Location schemas are designed to:

• Validate location data before processing
• Ensure location data consistency across the application
• Provide clear contracts for location API endpoints
• Enable type safety with TypeScript integration
• Support composition with other location blocks
• Handle hierarchical relationships with parent-child validation

---

📋 Location Schema Types

Base Location Schemas

Core location entity structures used as foundations for other schemas.

Location Creation Schemas

Schemas for location creation with required field validation and hierarchical parent support.

Location Retrieval Schemas

Schemas for getting specific locations with identifier validation.

Location Update Schemas

Schemas for location modifications with optional field validation.

Location Search Schemas

Schemas for location filtering and pagination parameters.

Location Deletion Schemas

Schemas for location removal operations.

---

🔧 Available Location Schemas

locationSchema

Location base schema with core properties for location entities.

Purpose: Defines the fundamental structure for all location entities with required and optional fields.

Schema Details:

• Type: object
• Properties: code (string), name (string), type (string)
• Additional Properties: false (strict validation)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { locationSchema } = schemas;

// Use in schema composition
export const customLocationSchema = withSchema({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          ...locationSchema,
          required: ['name', 'code', 'type']
        }
      }
    }
  }
});

---

createLocationSchema

Location creation schema with required fields validation for new location registration.

Purpose: Validates requests for creating new locations with proper hierarchical parent support and required field validation.

Schema Details:

• Request Body: required
• Content-Type: application/json
• Properties:
  • name: string (required) - Human-readable location name
  • code: string (required) - Unique location identifier code
  • type: string (required) - Location type classification (e.g., 'ORGANIZATION', 'REGION', 'CITY', 'BUILDING')
  • parentId: string (optional) - ID of the parent location for hierarchical relationships
• Additional Properties: false (strict validation)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { createLocationSchema } = schemas;

const schema = createLocationSchema({});
const validate = ajv.compile(schema.schemas as SchemaDefinition);
const isValid = validate({
  requestBody: {
    content: {
      'application/json': {
        schema: {
          name: 'Downtown Office',
          code: 'DTO-001',
          type: 'BUILDING',
          parentId: 'city-123'
        }
      }
    }
  }
});

---

getLocationSchema

Location retrieval schema with path parameter validation for single location lookup.

Purpose: Validates requests for retrieving individual locations by their IDs with proper path parameter validation.

Schema Details:

• Parameters: locationId (path parameter, required)
• Type: Path parameter validation only
• Request Body: Not applicable (GET request)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { getLocationSchema } = schemas;

const schema = getLocationSchema({});
const validate = ajv.compile(schema.schemas as SchemaDefinition);
const isValid = validate({
  parameters: [{ locationId: 'loc-123' }]
});

---

updateLocationSchema

Location update schema with optional fields validation for partial location updates.

Purpose: Validates requests for updating existing locations with partial field modifications, supporting flexible update operations.

Schema Details:

• Parameters: locationId (path parameter, required)
• Request Body: required
• Content-Type: application/json
• Properties:
  • name: string (optional) - Human-readable location name
  • code: string (optional) - Unique location identifier code
  • type: string (optional) - Location type classification
• Additional Properties: false (strict validation)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { updateLocationSchema } = schemas;

const schema = updateLocationSchema({});
const validate = ajv.compile(schema.schemas as SchemaDefinition);
const isValid = validate({
  parameters: [{ locationId: 'loc-123' }],
  requestBody: {
    content: {
      'application/json': {
        schema: {
          name: 'Updated Name'
        }
      }
    }
  }
});

---

deleteLocationSchema

Location deletion schema with path parameter validation for location removal.

Purpose: Validates requests for deleting existing locations with proper path parameter validation and security constraints.

Schema Details:

• Parameters: locationId (path parameter, required)
• Type: Path parameter validation only
• Request Body: Not applicable (DELETE request)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { deleteLocationSchema } = schemas;

const schema = deleteLocationSchema({});
const validate = ajv.compile(schema.schemas as SchemaDefinition);
const isValid = validate({
  parameters: [{ locationId: 'loc-123' }]
});

---

findLocationsSchema

Location search schema with pagination query validation.

Purpose: Validates requests for searching and listing locations with pagination parameters, providing a foundation for extensible location discovery.

Schema Details:

• Type: Query parameter validation only
• Query Parameters: page (optional, 1-1000), limit (optional, 1-50)
• Request Body: Not applicable (GET request)

Usage:

import { schemas } from '@nodeblocks/backend-sdk';

const { findLocationsSchema } = schemas;

const schema = findLocationsSchema({});
const validate = ajv.compile(schema.schemas as SchemaDefinition);
const isValid = validate({
  parameters: [
    { in: 'query', name: 'page', value: 2 },
    { in: 'query', name: 'limit', value: 20 }
  ]
});

---

🔗 Related Documentation

• Location Blocks - Location business logic functions
• Location Routes - HTTP endpoint definitions