バージョン: 🚧 Canary

🔍 Organization Schemas

Organization schemas provide JSON Schema definitions for organization data validation in Nodeblocks applications. These schemas ensure data integrity and provide clear contracts for organization-related API endpoints.

🎯 Overview

Organization schemas are designed to:

Validate organization data before processing
Support member role management within organizations
Handle organization membership and permissions
Enable organization search and filtering capabilities
Support multi-tenant applications with organization isolation
Provide contact and address management

📋 Organization Schema Types

Base Organization Schemas

Core organization structures used as foundations for other schemas.

Organization Creation Schemas

Schemas for organization creation with required field validation.

Organization Update Schemas

Schemas for organization modifications with optional field validation.

Organization Member Management Schemas

Schemas for managing member roles and membership in organizations.

Organization Query Schemas

Schemas for organization filtering and pagination parameters.

🔧 Available Organization Schemas

`organizationSchema`

Base organization schema defining the structure for organization data.

Purpose: Defines the structure for organization data with contact information

Schema Details:

Type: object
Required Fields: None (base schema)
Additional Properties: false (strict validation)
Properties:
- name?: string - Organization name (minimum length 1)
- description?: string - Organization description
- contact_email?: string - Organization contact email (email format)
- contact_phone?: string - Organization contact phone number
- address?: object - Organization address object
- logo?: { objectId: string; type: string } | null - Organization logo descriptor or null

Usage:

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

const { organizationSchema } = schemas;

const validate = ajv.compile(organizationSchema as SchemaDefinition);
const isValid = validate({
  name: 'Acme Corporation',
  description: 'A leading technology company',
  contact_email: 'contact@acme.com',
});

`createOrganizationSchema`

Organization creation schema with required fields for new organizations.

Purpose: Validates organization data during creation

Schema Details:

Type: object
Required Fields: organization.name, organization.description, organization.contact_email, ownerId
Optional Fields: organization.contact_phone, organization.address, parentId
Additional Properties: false (strict validation)
Content-Type: application/json
Request Body: required

Usage:

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

const { createOrganizationSchema } = schemas;

const organizationSchema = createOrganizationSchema({});
const validate = ajv.compile(organizationSchema.schemas as SchemaDefinition);
const isValid = validate({
  organization: {
    name: 'Acme Corporation',
    description: 'A leading technology company',
    contact_email: 'contact@acme.com',
    contact_phone: '+1-555-0123'
  },
  ownerId: 'identity123'
});

`organizationMembersSchema`

Organization members schema for managing member roles in organizations.

Purpose: Defines the structure for organization member assignments

Schema Details:

Type: array
Required Fields: identityId, role (for each item)
Minimum Items: 1
Additional Properties: false (strict validation)
Properties:
- identityId: string - Member identity ID
- role: string - Member role in organization

Usage:

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

const { organizationMembersSchema } = schemas;

const validate = ajv.compile(organizationMembersSchema as SchemaDefinition);
const isValid = validate([
  { identityId: 'identity1', role: 'admin' },
  { identityId: 'identity2', role: 'member' }
]);

`upsertOrganizationMembersSchema`

Organization members upsert schema for managing member roles in organization.

Purpose: Validates member role assignments for organization

Schema Details:

Type: array
Required Fields: identityId, role (for each item)
Minimum Items: 1
Additional Properties: false (strict validation)
Content-Type: application/json
Parameters: organizationId (path parameter)
Request Body: required

Usage:

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

const { upsertOrganizationMembersSchema } = schemas;

const membersSchema = upsertOrganizationMembersSchema({});
const validate = ajv.compile(membersSchema.schemas as SchemaDefinition);
const isValid = validate([
  { identityId: 'identity1', role: 'admin' },
  { identityId: 'identity2', role: 'member' }
]);

`updateOrganizationSchema`

Organization update schema with optional fields for organization modifications.

Purpose: Validates partial organization data updates

Schema Details:

Type: object
Required Fields: None (all fields optional)
Additional Properties: false (strict validation)
Content-Type: application/json
Parameters: organizationId (path parameter)
Request Body: required

Usage:

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

const { updateOrganizationSchema } = schemas;

const organizationSchema = updateOrganizationSchema({});
const validate = ajv.compile(organizationSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  description: 'Updated description',
  contact_phone: '+1-555-9999'
});

`getOrganizationSchema`

Organization retrieval schema for getting single organizations.

Purpose: Validates requests for retrieving specific organizations

Schema Details:

Parameters: organizationId (path parameter)
Purpose: Validates requests for retrieving specific organizations

Usage:

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

const { getOrganizationSchema } = schemas;

const organizationSchema = getOrganizationSchema({});
const validate = ajv.compile(organizationSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  organizationId: 'org123' 
});

`deleteOrganizationSchema`

Organization deletion schema for removing organizations.

Purpose: Validates requests for deleting specific organizations

Schema Details:

Parameters: organizationId (path parameter)
Purpose: Validates requests for deleting specific organizations

Usage:

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

const { deleteOrganizationSchema } = schemas;

const organizationSchema = deleteOrganizationSchema({});
const validate = ajv.compile(organizationSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  organizationId: 'org123' 
});

`getOrganizationMemberRoleSchema`

Organization member role retrieval schema for getting member roles in organizations.

Purpose: Validates requests for retrieving member roles in organizations

Schema Details:

Parameters: organizationId, identityId (path parameters)
Purpose: Validates requests for retrieving member roles in organizations

Usage:

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

const { getOrganizationMemberRoleSchema } = schemas;

const memberRoleSchema = getOrganizationMemberRoleSchema({});
const validate = ajv.compile(memberRoleSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  organizationId: 'org123',
  identityId: 'identity456' 
});

`checkOrganizationMemberExistenceSchema`

Organization member existence check schema for verifying member membership.

Purpose: Validates requests for checking member existence in organizations

Schema Details:

Parameters: organizationId (path parameter), identityId (query parameter)
Purpose: Validates requests for checking member existence in organizations

Usage:

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

const { checkOrganizationMemberExistenceSchema } = schemas;

const memberExistenceSchema = checkOrganizationMemberExistenceSchema({});
const validate = ajv.compile(memberExistenceSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  organizationId: 'org123',
  identityId: 'identity456' 
});

`findOrganizationMembersSchema`

Organization members search schema for finding members in organizations.

Purpose: Validates requests for finding members in organizations

Schema Details:

Parameters: organizationId (path parameter)
Purpose: Validates requests for finding members in organizations

Usage:

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

const { findOrganizationMembersSchema } = schemas;

const membersSchema = findOrganizationMembersSchema({});
const validate = ajv.compile(membersSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  organizationId: 'org123' 
});

`deleteOrganizationMemberSchema`

Organization member deletion schema for removing members from organizations.

Purpose: Validates requests for removing members from organizations

Schema Details:

Parameters: organizationId, identityId (path parameters)
Purpose: Validates requests for removing members from organizations

Usage:

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

const { deleteOrganizationMemberSchema } = schemas;

const memberDeletionSchema = deleteOrganizationMemberSchema({});
const validate = ajv.compile(memberDeletionSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  organizationId: 'org123',
  identityId: 'identity456' 
});

`findOrganizationsForMemberSchema`

Schema for finding organizations for a given member, with optional role and includeInherited query parameters.

Purpose: Validates requests for organizations associated with a specific member, optionally filtered by role and inheritance

Schema Details:

Path Parameters: identityId (required)
Query Parameters: roles?, includeInherited?

Usage:

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

const { findOrganizationsForMemberSchema } = schemas;

const memberOrgsSchema = findOrganizationsForMemberSchema({});
const validate = ajv.compile(memberOrgsSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  identityId: 'identity456',
  roles: 'admin',
  includeInherited: true
});

`findOrganizationsSchema`

Organizations search schema for finding organizations with filtering and pagination.

Purpose: Validates requests for searching and paginating organizations

Schema Details:

Query Parameters:
- contact_email?: string - Filter by contact email (email format)
- contact_phone?: string - Filter by contact phone
- description?: string - Filter by description
- name?: string - Filter by name (minimum length 1)
- page?: number - Pagination page number
- limit?: number - Pagination limit
Purpose: Validates requests for searching and paginating organizations

Usage:

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

const { findOrganizationsSchema } = schemas;

const organizationsSchema = findOrganizationsSchema({});
const validate = ajv.compile(organizationsSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  name: 'Acme',
  contact_email: 'contact@acme.com',
  page: 1,
  limit: 10 
});

`findOrganizationDescendantsSchema`

Organization descendants retrieval schema for getting descendant organizations in hierarchy.

Purpose: Validates requests for retrieving descendant organizations with optional depth control

Schema Details:

Parameters: organizationId (path parameter), depth? (optional query parameter, number >= 1)

Usage:

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

const { findOrganizationDescendantsSchema } = schemas;

const descendantsSchema = findOrganizationDescendantsSchema({});
const validate = ajv.compile(descendantsSchema.schemas as SchemaDefinition);
const isValid = validate({ 
  organizationId: 'org123',
  depth: 2
});

`getCertificateUploadUrlSchema`

Organization certificate upload URL schema with required query validation.

Purpose: Validates certificate upload URL generation requests with file type and size validation

Schema Details:

Type: object
Required Fields: organizationId (path parameter), contentType (query parameter), contentLength (query parameter)
Allowed Content Types:
- application/pdf - PDF certificates
- image/gif - GIF images
- image/jpeg - JPEG images
- image/png - PNG images
Max Content Length: 10MB (enforced via contentLengthQueryParameter)
Response: { objectId: string; url: string } - UUID object ID and signed upload URL

Schema Structure:

{
  contentType: "application/pdf" | "image/gif" | "image/jpeg" | "image/png"; // required
  contentLength: number; // required - file size in bytes (max 10MB)
}

Usage:

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

const { getCertificateUploadUrlSchema } = schemas;

// Apply to feature composition:
export const getCertificateUploadUrlFeature = compose(
  getCertificateUploadUrlSchema,
  getCertificateUploadUrlRoute
);

`createChangeRequestSchema`

Organization change request creation schema with request body validation.

Purpose: Validates organization change request submissions with flexible field support

Schema Details:

Type: object
Required Fields: organizationId (path parameter), at least 1 property in request body
Optional Request Body Fields:
- name?: string - Organization name (minimum length 1)
- addressLine1?: string - Address line 1
- addressLine2?: string - Address line 2
- addressLine3?: string - Address line 3
- branchName?: string - Branch name
- postalCode?: string - Postal code
- typeId?: string - Organization type ID
- certificateImage?: { objectId: string; type: string } - Certificate image reference
- certifiedQualifications?: Array<{ name: string; status: string; value: string }> - Qualifications list
Response: 204 No Content - Empty response body on success
Additional Properties: false (strict validation)
Min Properties: 1 (at least one field must be provided)

Schema Structure:

{
  addressLine1?: string;  // optional - address line 1
  addressLine2?: string;  // optional - address line 2
  addressLine3?: string;  // optional - address line 3
  branchName?: string;    // optional - branch name
  certificateImage?: {    // optional - certificate image reference
    objectId: string;     // required - storage object id (uuid)
    type: string;         // required - MIME type
  };
  certifiedQualifications?: { // optional - qualifications list
    name: string;         // required - qualification name
    status: string;       // required - qualification status
    value: string;        // required - qualification value
  }[];
  name?: string;          // optional - organization name (min length 1)
  postalCode?: string;    // optional - postal code
  typeId?: string;        // optional - organization type ID
}

Key Features:

Flexible schema supporting partial organization updates
Certificate image upload support with objectId references
Certified qualifications tracking with structured data
Automatic audit status update to waiting_for_review
Token-based authentication with identity extraction

Usage:

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

const { createChangeRequestSchema } = schemas;

// Apply to feature composition:
export const createChangeRequestFeature = compose(
  createChangeRequestSchema,
  createChangeRequestRoute
);

// Example request body:
const changeRequest = {
  name: 'Updated Organization Name',
  addressLine1: '123 Main Street',
  certificateImage: {
    objectId: '550e8400-e29b-41d4-a716-446655440000',
    type: 'application/pdf'
  },
  certifiedQualifications: [
    {
      name: 'ISO 9001:2015',
      status: 'approved',
      value: '2024'
    }
  ]
};

`findChangeRequestsForOrganizationSchema`

Organization change requests retrieval schema with pagination support.

Purpose: Validates parameters for retrieving change requests for a specific organization

Schema Details:

Type: object
Required Fields: organizationId (path parameter)
Optional Query Parameters:
- page?: number - Pagination page number (1-1000, default: 1)
- limit?: number - Pagination limit per page (1-50, default: 10)
Additional Properties: false (strict validation)

Schema Structure:

{
  organizationId: string;      // required - path parameter for organization
  page?: number;               // optional - pagination page (1-1000)
  limit?: number;              // optional - pagination size (1-50)
}

Key Features:

Path parameter validation for organization ID
Pagination query parameter support
Reuses standard pagination schema parameters

Usage:

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

const { findChangeRequestsForOrganizationSchema } = schemas;

// Apply to feature composition:
export const findChangeRequestsForOrganizationFeature = compose(
  findChangeRequestsForOrganizationSchema,
  findChangeRequestsForOrganizationRoute
);

// Example URL:
/organizations/org-123/change-requests?page=1&limit=20

`updateOrganizationAsAdminSchema`

Organization admin update schema with path and extended request body validation.

Purpose: Validates admin-level organization updates with access to all fields including audit status

Schema Details:

Type: object
Required Fields: organizationId (path parameter)
Optional Request Body Fields:
- Common Fields (available to all users):
  - branchName?: string - Branch name
  - contact_email?: string - Contact email (email format)
  - contact_phone?: string - Contact phone
  - description?: string - Organization description
- Admin-Approved Fields (admin-only updates):
  - name?: string - Organization name (minimum length 1)
  - address?: object - Address information
  - certificateImage?: { objectId: string; type: string } - Certificate image reference
  - certifiedQualifications?: Array<{ name: string; status: string; value: string }> - Qualifications list
  - logo?: { objectId: string; type: string } | null - Logo reference or null
  - typeId?: string - Organization type ID
  - auditStatus?: string - Audit status (validated by validateAuditStatus block, not schema)
Response: 200 OK - Returns updated organization with normalized logo URL
Additional Properties: false (strict validation)

Schema Structure:

{
  organizationId: string;   // required - path param (organization ID)
}

Request body (application/json):
{
  // Common fields
  branchName?: string;                 // optional - branch name
  contact_email?: string;              // optional - contact email (email format)
  contact_phone?: string;              // optional - contact phone
  description?: string;                // optional - description

  // Admin-approved fields
  name?: string;                       // optional - organization name (min length 1)
  address?: object;                    // optional - address information
  certificateImage?: {                 // optional - certificate image reference
    objectId: string;                  // required - storage object id (uuid)
    type: string;                      // required - MIME type
  };
  certifiedQualifications?: {          // optional - qualifications list
    name: string;                      // required - qualification name
    status: string;                    // required - qualification status
    value: string;                     // required - qualification value
  }[];
  logo?: { objectId: string; type: string } | null; // optional - logo reference or null
  typeId?: string;                     // optional - organization type ID
  
  // Note: auditStatus is validated in validateAuditStatus block, not in schema
  auditStatus?: string;                // optional - audit status (validated elsewhere)
}

Key Features:

Admin-only access (requires admin identity type)
Extended field access including name changes
Support for certificate images and certified qualifications
Audit status updates for change request workflow
All common fields plus admin-approved fields available
Flexible partial updates (all fields optional)

Usage:

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

const { updateOrganizationAsAdminSchema } = schemas;

// Apply to feature composition:
export const updateOrganizationAsAdminFeature = compose(
  updateOrganizationAsAdminSchema,
  updateOrganizationAsAdminRoute
);

// Example request body:
const adminUpdate = {
  name: 'Updated Organization Name',
  auditStatus: 'approved',
  certificateImage: {
    objectId: '550e8400-e29b-41d4-a716-446655440000',
    type: 'application/pdf'
  },
  certifiedQualifications: [
    {
      name: 'ISO 9001:2015',
      status: 'approved',
      value: '2024'
    }
  ]
};

`findByOrganizationIdSchema`

Organization-scoped resource retrieval schema with path parameter validation and pagination support.

Purpose: Validates requests for retrieving resources scoped to a specific organization, ensuring organization ID is provided and supporting pagination parameters.

Schema Details:

Type: object
Required Fields: organizationId (path parameter)
Optional Query Parameters: page, limit (for pagination)
Request Body: Not required (empty body)
Content-Type: N/A (no body validation)
Path Parameters: Required

Schema Structure:

{
  parameters: [
    {
      in: 'path',
      name: 'organizationId',
      required: true,
      schema: { type: 'string' }
    }
  ]
}

Query parameters (optional):
{
  page?: number;   // optional - page number for pagination (default: 1)
  limit?: number;  // optional - results per page (default: 10)
}

Key Features:

Path Parameter Validation: Ensures organization ID is provided in URL path
No Body Validation: Resource retrieval requires no request body
Pagination Support: Accepts optional page and limit query parameters
Type Safety: Validates string type for organization identifier

Usage:

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

const { findByOrganizationIdSchema } = schemas;

// Apply to route
const route = withRoute({
  handler: findResourcesByOrganizationIdHandler,
  method: 'GET',
  path: '/resources/organizations/:organizationId'
});

const validatedRoute = findByOrganizationIdSchema(route);

Common Use Cases:

Finding orders by organization ID
Finding products by organization ID
Finding any organization-scoped resources with pagination

`getOrganizationFollowersSchema`

Organization followers retrieval schema with path parameter validation and pagination support.

Purpose: Validates requests for retrieving followers of an organization, ensuring organization ID is provided and supporting pagination parameters.

Schema Details:

Type: object
Required Fields: organizationId (path parameter)
Optional Query Parameters: page, limit (for pagination)
Request Body: Not required (empty body)
Content-Type: N/A (no body validation)
Path Parameters: Required

Schema Structure:

{
  parameters: [
    {
      in: 'path',
      name: 'organizationId',
      required: true,
      schema: { type: 'string' }
    }
  ]
}

Query parameters (optional):
{
  page?: number;   // optional - page number for pagination (default: 1)
  limit?: number;  // optional - results per page (default: 20)
}

Key Features:

Path Parameter Validation: Ensures organization ID is provided in URL path
No Body Validation: Followers retrieval requires no request body
Pagination Support: Accepts optional page and limit query parameters
Type Safety: Validates string type for organization identifier

Usage:

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

const { getOrganizationFollowersSchema } = schemas;

// Apply to route
const route = withRoute({
  handler: getOrganizationFollowersHandler,
  method: 'GET',
  path: '/organizations/:organizationId/followers'
});

const validatedRoute = getOrganizationFollowersSchema(route);

Validation Rules:

organizationId path parameter is required and must be a valid string
No additional path parameters are allowed
No request body is expected or validated
Query parameters page and limit are optional

Common Validation Errors:

Missing required organizationId path parameter
Invalid parameter type (non-string organizationId)
Additional unexpected path parameters

API Endpoint Structure:

GET /organizations/{organizationId}/followers?page=1&limit=20

Example Valid Requests:

# 🔍 first page of followers for organization org-123
GET /api/organizations/org-123/followers
Authorization: Bearer <token>

# 🔍 second page with 50 results per page
GET /api/organizations/org-123/followers?page=2&limit=50
Authorization: Bearer <token>

Example Invalid Requests:

# 🔍 organizationId
GET /api/organizations//followers
# 🔍 400 Bad Request - "path parameter 'organizationId' is required"

# 🔍 organizationId type
GET /api/organizations/123/followers
# 🔍 fail if organization ID validation expects specific format

Response Schema: The validated route returns paginated follower data:

{
  data: [
    {
      id: string;
      name: string;
      avatar: {
        url: string;
        type: string;
      }
    }
  ],
  metadata: {
    pagination: {
      page: number;
      limit: number;
      total: number;
      totalPages: number;
    }
  }
}

Organization Domain Overview - Organization domain overview

🎯 Overview​

📋 Organization Schema Types​

Base Organization Schemas​

Organization Creation Schemas​

Organization Update Schemas​

Organization Member Management Schemas​

Organization Query Schemas​

🔧 Available Organization Schemas​

organizationSchema​

createOrganizationSchema​

organizationMembersSchema​

upsertOrganizationMembersSchema​

updateOrganizationSchema​

getOrganizationSchema​

deleteOrganizationSchema​

getOrganizationMemberRoleSchema​

checkOrganizationMemberExistenceSchema​

findOrganizationMembersSchema​

deleteOrganizationMemberSchema​

findOrganizationsForMemberSchema​

findOrganizationsSchema​

findOrganizationDescendantsSchema​

getCertificateUploadUrlSchema​

createChangeRequestSchema​

findChangeRequestsForOrganizationSchema​

updateOrganizationAsAdminSchema​

findByOrganizationIdSchema​

getOrganizationFollowersSchema​

🔗 Related Documentation​

🎯 Overview

📋 Organization Schema Types

Base Organization Schemas

Organization Creation Schemas

Organization Update Schemas

Organization Member Management Schemas

Organization Query Schemas

🔧 Available Organization Schemas

`organizationSchema`

`createOrganizationSchema`

`organizationMembersSchema`

`upsertOrganizationMembersSchema`

`updateOrganizationSchema`

`getOrganizationSchema`

`deleteOrganizationSchema`

`getOrganizationMemberRoleSchema`

`checkOrganizationMemberExistenceSchema`

`findOrganizationMembersSchema`

`deleteOrganizationMemberSchema`

`findOrganizationsForMemberSchema`

`findOrganizationsSchema`

`findOrganizationDescendantsSchema`

`getCertificateUploadUrlSchema`

`createChangeRequestSchema`

`findChangeRequestsForOrganizationSchema`

`updateOrganizationAsAdminSchema`

`findByOrganizationIdSchema`

`getOrganizationFollowersSchema`

🔗 Related Documentation