@pacp/spec 3.4.2 → 3.6.0

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/schema.ts","../src/validate.ts"],"sourcesContent":["export { schema, profiles, profileIds } from \"./schema.js\";\r\nexport { validate } from \"./validate.js\";\r\nexport type {\r\n  ScalarValue,\r\n  ImageType,\r\n  Image,\r\n  Measure,\r\n  PhysicalDimensions,\r\n  AttributeRef,\r\n  AttributeValue,\r\n  Option,\r\n  LotPolicy,\r\n  SalesUnit,\r\n  SourceWhen,\r\n  SuppliedMaterial,\r\n  SuppliedMaterialCost,\r\n  SuppliedMaterialQuantity,\r\n  SuppliedMaterialSource,\r\n  SupplyOutputEntry,\r\n  Product,\r\n  Predicate,\r\n  Condition,\r\n  Component,\r\n  RuleOperation,\r\n  Rule,\r\n  Ruleset,\r\n  LookupAxis,\r\n  TableRow,\r\n  Table,\r\n  Dependency,\r\n  Constraint,\r\n  PriceList,\r\n  Catalog,\r\n  ProductRef,\r\n  Context,\r\n  Pricing,\r\n  CatalogDocument,\r\n  ProductDocument,\r\n  PacpDocument,\r\n  ProfileId,\r\n  ValidationIssue,\r\n  ValidationResult,\r\n} from \"./types.js\";\r\n","import { readFileSync } from \"node:fs\";\r\nimport { join } from \"node:path\";\r\n\r\nfunction loadJson(relativePath: string): Record<string, unknown> {\r\n  const fullPath = join(__dirname, relativePath);\r\n  return JSON.parse(readFileSync(fullPath, \"utf8\"));\r\n}\r\n\r\nexport const schema = loadJson(\"./pacp.schema.json\") as Record<string, unknown>;\r\n\r\nexport const profiles = {\r\n  moveis: loadJson(\"./profiles/moveis.schema.json\") as Record<string, unknown>,\r\n  iluminacao: loadJson(\"./profiles/iluminacao.schema.json\") as Record<string, unknown>,\r\n  \"pisos-revestimentos\": loadJson(\"./profiles/pisos-revestimentos.schema.json\") as Record<string, unknown>,\r\n  \"fiscal-br\": loadJson(\"./profiles/fiscal-br.schema.json\") as Record<string, unknown>,\r\n} as const;\r\n\r\nexport type ProfileId = keyof typeof profiles;\r\n\r\nexport const profileIds = Object.keys(profiles) as ProfileId[];\r\n","import type { ValidationResult, ValidationIssue, PacpDocument } from \"./types.js\";\r\nimport { schema, profiles, type ProfileId } from \"./schema.js\";\r\n\r\nexport function validate(document: unknown): ValidationResult {\r\n  let Ajv2020: typeof import(\"ajv/dist/2020\").default;\r\n  let addFormats: typeof import(\"ajv-formats\").default;\r\n\r\n  try {\r\n    Ajv2020 = require(\"ajv/dist/2020\") as typeof import(\"ajv/dist/2020\").default;\r\n    addFormats = require(\"ajv-formats\") as typeof import(\"ajv-formats\").default;\r\n  } catch {\r\n    throw new Error(\r\n      'Para usar validate(), instale ajv e ajv-formats: npm install ajv ajv-formats'\r\n    );\r\n  }\r\n\r\n  const ajv = new Ajv2020({ allErrors: true, strict: false });\r\n  addFormats(ajv);\r\n\r\n  const issues: ValidationIssue[] = [];\r\n\r\n  const validateSchema = ajv.compile(schema);\r\n  const valid = validateSchema(document);\r\n\r\n  if (!valid && validateSchema.errors) {\r\n    for (const error of validateSchema.errors) {\r\n      issues.push({\r\n        code: \"SCHEMA\",\r\n        path: error.instancePath || \"/\",\r\n        message: error.message ?? \"Erro de validacao de schema\",\r\n      });\r\n    }\r\n  }\r\n\r\n  if (document && typeof document === \"object\" && !Array.isArray(document)) {\r\n    const doc = document as Record<string, unknown>;\r\n    const declaredProfiles = Array.isArray(doc.profiles) ? doc.profiles : [];\r\n\r\n    for (const profileId of declaredProfiles) {\r\n      if (typeof profileId !== \"string\") continue;\r\n\r\n      const profileSchema = profiles[profileId as ProfileId];\r\n      if (!profileSchema) {\r\n        issues.push({\r\n          code: \"UNKNOWN_PROFILE\",\r\n          path: \"/profiles\",\r\n          message: `Profile \"${profileId}\" nao e um profile oficial PACP`,\r\n        });\r\n        continue;\r\n      }\r\n\r\n      const products = extractProducts(doc);\r\n      const validateProfile = ajv.compile(profileSchema);\r\n\r\n      for (let i = 0; i < products.length; i++) {\r\n        const xFields = extractXFields(products[i]);\r\n        if (Object.keys(xFields).length === 0) continue;\r\n\r\n        const profileValid = validateProfile(xFields);\r\n        if (!profileValid && validateProfile.errors) {\r\n          for (const error of validateProfile.errors) {\r\n            issues.push({\r\n              code: \"PROFILE_VALIDATION\",\r\n              path: `products[${i}]${error.instancePath || \"/\"}`,\r\n              message: `Profile \"${profileId}\": ${error.message ?? \"erro de validacao\"}`,\r\n            });\r\n          }\r\n        }\r\n      }\r\n    }\r\n  }\r\n\r\n  return { valid: issues.length === 0, issues };\r\n}\r\n\r\nfunction extractProducts(doc: Record<string, unknown>): Record<string, unknown>[] {\r\n  if (doc.document_type === \"PRODUCT\" && doc.product && typeof doc.product === \"object\") {\r\n    return [doc.product as Record<string, unknown>];\r\n  }\r\n  return [];\r\n}\r\n\r\nfunction extractXFields(obj: Record<string, unknown>): Record<string, unknown> {\r\n  const result: Record<string, unknown> = {};\r\n  for (const [key, value] of Object.entries(obj)) {\r\n    if (key.startsWith(\"x-\")) {\r\n      result[key] = value;\r\n    }\r\n  }\r\n  return result;\r\n}\r\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/schema.ts","../src/validate.ts"],"sourcesContent":["export { schema, profiles, profileIds } from \"./schema.js\";\r\nexport { validate } from \"./validate.js\";\r\nexport type {\r\n  ScalarValue,\r\n  ImageType,\r\n  Image,\r\n  Measure,\r\n  PhysicalDimensions,\r\n  AttributeRef,\r\n  AttributeValue,\r\n  Option,\r\n  LotPolicy,\r\n  SalesUnit,\r\n  SourceWhen,\r\n  SuppliedMaterial,\r\n  SuppliedMaterialCost,\r\n  SuppliedMaterialQuantity,\r\n  SuppliedMaterialSource,\r\n  SupplyOutputEntry,\r\n  Product,\r\n  ProductRole,\r\n  Predicate,\r\n  Condition,\r\n  Component,\r\n  RuleOperation,\r\n  Rule,\r\n  Ruleset,\r\n  LookupAxis,\r\n  TableRow,\r\n  Table,\r\n  Dependency,\r\n  Constraint,\r\n  PriceList,\r\n  Catalog,\r\n  ProductRef,\r\n  Context,\r\n  Pricing,\r\n  CatalogDocument,\r\n  ProductDocument,\r\n  PacpDocument,\r\n  ProfileId,\r\n  ValidationIssue,\r\n  ValidationResult,\r\n} from \"./types.js\";\r\n","import { readFileSync } from \"node:fs\";\r\nimport { join } from \"node:path\";\r\n\r\nfunction loadJson(relativePath: string): Record<string, unknown> {\r\n  const fullPath = join(__dirname, relativePath);\r\n  return JSON.parse(readFileSync(fullPath, \"utf8\"));\r\n}\r\n\r\nexport const schema = loadJson(\"./pacp.schema.json\") as Record<string, unknown>;\r\n\r\nexport const profiles = {\r\n  moveis: loadJson(\"./profiles/moveis.schema.json\") as Record<string, unknown>,\r\n  iluminacao: loadJson(\"./profiles/iluminacao.schema.json\") as Record<string, unknown>,\r\n  \"pisos-revestimentos\": loadJson(\"./profiles/pisos-revestimentos.schema.json\") as Record<string, unknown>,\r\n  \"fiscal-br\": loadJson(\"./profiles/fiscal-br.schema.json\") as Record<string, unknown>,\r\n} as const;\r\n\r\nexport type ProfileId = keyof typeof profiles;\r\n\r\nexport const profileIds = Object.keys(profiles) as ProfileId[];\r\n","import type { ValidationResult, ValidationIssue, PacpDocument } from \"./types.js\";\r\nimport { schema, profiles, type ProfileId } from \"./schema.js\";\r\n\r\nexport function validate(document: unknown): ValidationResult {\r\n  let Ajv2020: typeof import(\"ajv/dist/2020\").default;\r\n  let addFormats: typeof import(\"ajv-formats\").default;\r\n\r\n  try {\r\n    Ajv2020 = require(\"ajv/dist/2020\") as typeof import(\"ajv/dist/2020\").default;\r\n    addFormats = require(\"ajv-formats\") as typeof import(\"ajv-formats\").default;\r\n  } catch {\r\n    throw new Error(\r\n      'Para usar validate(), instale ajv e ajv-formats: npm install ajv ajv-formats'\r\n    );\r\n  }\r\n\r\n  const ajv = new Ajv2020({ allErrors: true, strict: false });\r\n  addFormats(ajv);\r\n\r\n  const issues: ValidationIssue[] = [];\r\n\r\n  const validateSchema = ajv.compile(schema);\r\n  const valid = validateSchema(document);\r\n\r\n  if (!valid && validateSchema.errors) {\r\n    for (const error of validateSchema.errors) {\r\n      issues.push({\r\n        code: \"SCHEMA\",\r\n        path: error.instancePath || \"/\",\r\n        message: error.message ?? \"Erro de validacao de schema\",\r\n      });\r\n    }\r\n  }\r\n\r\n  if (document && typeof document === \"object\" && !Array.isArray(document)) {\r\n    const doc = document as Record<string, unknown>;\r\n    const declaredProfiles = Array.isArray(doc.profiles) ? doc.profiles : [];\r\n\r\n    for (const profileId of declaredProfiles) {\r\n      if (typeof profileId !== \"string\") continue;\r\n\r\n      const profileSchema = profiles[profileId as ProfileId];\r\n      if (!profileSchema) {\r\n        issues.push({\r\n          code: \"UNKNOWN_PROFILE\",\r\n          path: \"/profiles\",\r\n          message: `Profile \"${profileId}\" nao e um profile oficial PACP`,\r\n        });\r\n        continue;\r\n      }\r\n\r\n      const products = extractProducts(doc);\r\n      const validateProfile = ajv.compile(profileSchema);\r\n\r\n      for (let i = 0; i < products.length; i++) {\r\n        const xFields = extractXFields(products[i]);\r\n        if (Object.keys(xFields).length === 0) continue;\r\n\r\n        const profileValid = validateProfile(xFields);\r\n        if (!profileValid && validateProfile.errors) {\r\n          for (const error of validateProfile.errors) {\r\n            issues.push({\r\n              code: \"PROFILE_VALIDATION\",\r\n              path: `products[${i}]${error.instancePath || \"/\"}`,\r\n              message: `Profile \"${profileId}\": ${error.message ?? \"erro de validacao\"}`,\r\n            });\r\n          }\r\n        }\r\n      }\r\n    }\r\n  }\r\n\r\n  return { valid: issues.length === 0, issues };\r\n}\r\n\r\nfunction extractProducts(doc: Record<string, unknown>): Record<string, unknown>[] {\r\n  if (doc.document_type === \"PRODUCT\" && doc.product && typeof doc.product === \"object\") {\r\n    return [doc.product as Record<string, unknown>];\r\n  }\r\n  return [];\r\n}\r\n\r\nfunction extractXFields(obj: Record<string, unknown>): Record<string, unknown> {\r\n  const result: Record<string, unknown> = {};\r\n  for (const [key, value] of Object.entries(obj)) {\r\n    if (key.startsWith(\"x-\")) {\r\n      result[key] = value;\r\n    }\r\n  }\r\n  return result;\r\n}\r\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -238,6 +238,18 @@ interface SupplyOutputEntry {
     /** Requisitos copiados do `SuppliedMaterial.requirements`. */
     requirements?: Record<string, unknown>;
 }
+/**
+ * Papel do produto na hierarquia família/módulo. Ver spec §4.9.
+ *
+ * - `STANDALONE` (default quando ausente): produto vendido independentemente — comportamento PACP histórico.
+ * - `FAMILY`: agrupador conceitual sem SKU/preço próprios (ex.: linha de sofá modular ADANA).
+ *   Não pode ter `base_price` nem `family_product_id`. Pode listar seus módulos em `member_product_ids`.
+ * - `MODULE`: componente vendável vinculado a uma FAMILY via `family_product_id` (obrigatório).
+ *   Tem `base_price` próprio. Pode marcar `standalone_sellable=false` se só for vendido como parte da composição.
+ *
+ * Profundidade da hierarquia é 1 (FAMILY não pode ter `family_product_id`).
+ */
+type ProductRole = "STANDALONE" | "FAMILY" | "MODULE";
 /**
  * Produto único do catálogo. Ver spec §4.
  *
@@ -306,6 +318,14 @@ interface Product {
     supplied_materials?: SuppliedMaterial[];
     /** IDs de rulesets aplicados a este produto. */
     ruleset_ids?: string[];
+    /** Papel do produto na hierarquia. Default implícito quando ausente: `STANDALONE`. Ver spec §4.9. */
+    role?: ProductRole;
+    /** ID da família (produto com `role="FAMILY"`) à qual este módulo pertence. Obrigatório quando `role="MODULE"`; proibido em outros casos. */
+    family_product_id?: string;
+    /** IDs dos módulos pertencentes a esta família. Permitido apenas quando `role="FAMILY"`. */
+    member_product_ids?: string[];
+    /** `false` quando o módulo só pode ser vendido como parte da composição da família. Default `true`. Permitido apenas quando `role="MODULE"`. */
+    standalone_sellable?: boolean;
     [key: `x-${string}`]: unknown;
 }
 /**
@@ -475,6 +495,10 @@ interface PriceList {
 interface Catalog {
     id: string;
     name?: string;
+    /** Observações públicas sobre o catálogo. Consumidores PODEM exibir. */
+    notes?: string;
+    /** Anotações não-públicas. Consumidores que geram catálogos públicos DEVEM omitir. Ver spec §9.1. */
+    internal_notes?: string;
     default_price_list_id?: string;
     price_lists?: PriceList[];
     [key: `x-${string}`]: unknown;
@@ -564,4 +588,4 @@ interface ValidationResult {
 
 declare function validate(document: unknown): ValidationResult;
 
-export { type AttributeRef, type AttributeValue, type Catalog, type CatalogDocument, type Component, type Condition, type Constraint, type Context, type Dependency, type Image, type ImageType, type LookupAxis, type LotPolicy, type Measure, type Option, type PacpDocument, type PhysicalDimensions, type Predicate, type PriceList, type Pricing, type Product, type ProductDocument, type ProductRef, type ProfileId, type Rule, type RuleOperation, type Ruleset, type SalesUnit, type ScalarValue, type SourceWhen, type SuppliedMaterial, type SuppliedMaterialCost, type SuppliedMaterialQuantity, type SuppliedMaterialSource, type SupplyOutputEntry, type Table, type TableRow, type ValidationIssue, type ValidationResult, validate };
+export { type AttributeRef, type AttributeValue, type Catalog, type CatalogDocument, type Component, type Condition, type Constraint, type Context, type Dependency, type Image, type ImageType, type LookupAxis, type LotPolicy, type Measure, type Option, type PacpDocument, type PhysicalDimensions, type Predicate, type PriceList, type Pricing, type Product, type ProductDocument, type ProductRef, type ProductRole, type ProfileId, type Rule, type RuleOperation, type Ruleset, type SalesUnit, type ScalarValue, type SourceWhen, type SuppliedMaterial, type SuppliedMaterialCost, type SuppliedMaterialQuantity, type SuppliedMaterialSource, type SupplyOutputEntry, type Table, type TableRow, type ValidationIssue, type ValidationResult, validate };

package/dist/index.d.ts

@@ -238,6 +238,18 @@ interface SupplyOutputEntry {
     /** Requisitos copiados do `SuppliedMaterial.requirements`. */
     requirements?: Record<string, unknown>;
 }
+/**
+ * Papel do produto na hierarquia família/módulo. Ver spec §4.9.
+ *
+ * - `STANDALONE` (default quando ausente): produto vendido independentemente — comportamento PACP histórico.
+ * - `FAMILY`: agrupador conceitual sem SKU/preço próprios (ex.: linha de sofá modular ADANA).
+ *   Não pode ter `base_price` nem `family_product_id`. Pode listar seus módulos em `member_product_ids`.
+ * - `MODULE`: componente vendável vinculado a uma FAMILY via `family_product_id` (obrigatório).
+ *   Tem `base_price` próprio. Pode marcar `standalone_sellable=false` se só for vendido como parte da composição.
+ *
+ * Profundidade da hierarquia é 1 (FAMILY não pode ter `family_product_id`).
+ */
+type ProductRole = "STANDALONE" | "FAMILY" | "MODULE";
 /**
  * Produto único do catálogo. Ver spec §4.
  *
@@ -306,6 +318,14 @@ interface Product {
     supplied_materials?: SuppliedMaterial[];
     /** IDs de rulesets aplicados a este produto. */
     ruleset_ids?: string[];
+    /** Papel do produto na hierarquia. Default implícito quando ausente: `STANDALONE`. Ver spec §4.9. */
+    role?: ProductRole;
+    /** ID da família (produto com `role="FAMILY"`) à qual este módulo pertence. Obrigatório quando `role="MODULE"`; proibido em outros casos. */
+    family_product_id?: string;
+    /** IDs dos módulos pertencentes a esta família. Permitido apenas quando `role="FAMILY"`. */
+    member_product_ids?: string[];
+    /** `false` quando o módulo só pode ser vendido como parte da composição da família. Default `true`. Permitido apenas quando `role="MODULE"`. */
+    standalone_sellable?: boolean;
     [key: `x-${string}`]: unknown;
 }
 /**
@@ -475,6 +495,10 @@ interface PriceList {
 interface Catalog {
     id: string;
     name?: string;
+    /** Observações públicas sobre o catálogo. Consumidores PODEM exibir. */
+    notes?: string;
+    /** Anotações não-públicas. Consumidores que geram catálogos públicos DEVEM omitir. Ver spec §9.1. */
+    internal_notes?: string;
     default_price_list_id?: string;
     price_lists?: PriceList[];
     [key: `x-${string}`]: unknown;
@@ -564,4 +588,4 @@ interface ValidationResult {
 
 declare function validate(document: unknown): ValidationResult;
 
-export { type AttributeRef, type AttributeValue, type Catalog, type CatalogDocument, type Component, type Condition, type Constraint, type Context, type Dependency, type Image, type ImageType, type LookupAxis, type LotPolicy, type Measure, type Option, type PacpDocument, type PhysicalDimensions, type Predicate, type PriceList, type Pricing, type Product, type ProductDocument, type ProductRef, type ProfileId, type Rule, type RuleOperation, type Ruleset, type SalesUnit, type ScalarValue, type SourceWhen, type SuppliedMaterial, type SuppliedMaterialCost, type SuppliedMaterialQuantity, type SuppliedMaterialSource, type SupplyOutputEntry, type Table, type TableRow, type ValidationIssue, type ValidationResult, validate };
+export { type AttributeRef, type AttributeValue, type Catalog, type CatalogDocument, type Component, type Condition, type Constraint, type Context, type Dependency, type Image, type ImageType, type LookupAxis, type LotPolicy, type Measure, type Option, type PacpDocument, type PhysicalDimensions, type Predicate, type PriceList, type Pricing, type Product, type ProductDocument, type ProductRef, type ProductRole, type ProfileId, type Rule, type RuleOperation, type Ruleset, type SalesUnit, type ScalarValue, type SourceWhen, type SuppliedMaterial, type SuppliedMaterialCost, type SuppliedMaterialQuantity, type SuppliedMaterialSource, type SupplyOutputEntry, type Table, type TableRow, type ValidationIssue, type ValidationResult, validate };

package/dist/pacp.schema.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://cdn.jsdelivr.net/npm/@pacp/spec@latest/dist/pacp.schema.json",
-  "title": "PACP v3.4.2",
+  "title": "PACP v3.6.0",
   "oneOf": [
     {
       "$ref": "#/$defs/catalog_document"
@@ -183,6 +183,14 @@
           "type": "string",
           "minLength": 1
         },
+        "notes": {
+          "type": "string",
+          "description": "Observações públicas sobre o catálogo (vigência, escopo, instruções de uso). Texto livre, multilinha permitido. Consumidores PODEM exibir."
+        },
+        "internal_notes": {
+          "type": "string",
+          "description": "Anotações internas (não-públicas) sobre o catálogo. Consumidores que geram vitrines/catálogos públicos DEVEM omitir este campo. Ver spec §9.1."
+        },
         "default_price_list_id": {
           "type": "string",
           "minLength": 1
@@ -331,7 +339,7 @@
             },
             "minItems": 1
           },
-          "description": "Categorias hier\u00e1rquicas do produto. Cada item \u00e9 um path da raiz \u00e0 folha, ex.: [[\"M\u00f3veis\", \"Sof\u00e1\"], [\"Promo\u00e7\u00f5es\"]]."
+          "description": "Categorias hierárquicas do produto. Cada item é um path da raiz à folha, ex.: [[\"Móveis\", \"Sofá\"], [\"Promoções\"]]."
         },
         "gtin": {
           "type": "string",
@@ -364,7 +372,7 @@
             "type": "string",
             "minLength": 1
           },
-          "description": "Identificadores de cole\u00e7\u00f5es \u00e0s quais o produto pertence (ex.: \"verao_2026\", \"linha_premium\"). Cada item \u00e9 um ID est\u00e1vel, \u00fanico por cat\u00e1logo, com sem\u00e2ntica de agrupamento curatorial/sazonal."
+          "description": "Identificadores de coleções às quais o produto pertence (ex.: \"verao_2026\", \"linha_premium\"). Cada item é um ID estável, único por catálogo, com semântica de agrupamento curatorial/sazonal."
         },
         "weight": {
           "$ref": "#/$defs/measure"
@@ -401,7 +409,7 @@
           "items": {
             "$ref": "#/$defs/supplied_material"
           },
-          "description": "Materiais consumidos pelo produto, com sourcing factory/customer. Ver se\u00e7\u00e3o 4.8."
+          "description": "Materiais consumidos pelo produto, com sourcing factory/customer. Ver seção 4.8."
         },
         "ruleset_ids": {
           "type": "array",
@@ -409,6 +417,35 @@
             "type": "string",
             "minLength": 1
           }
+        },
+        "role": {
+          "type": "string",
+          "enum": [
+            "STANDALONE",
+            "FAMILY",
+            "MODULE"
+          ],
+          "default": "STANDALONE",
+          "description": "Papel do produto na hierarquia. STANDALONE (default, retrocompatível) é vendido independentemente. FAMILY é agrupador conceitual sem SKU/preço próprios (ex.: linha de sofá modular). MODULE é componente vendável vinculado a uma FAMILY. Ver spec §4.9."
+        },
+        "family_product_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Referência ao product.id de um produto com role=FAMILY no mesmo catalog document. Obrigatório quando role=MODULE; proibido para role=FAMILY ou STANDALONE."
+        },
+        "member_product_ids": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "uniqueItems": true,
+          "description": "Lista dos product.id dos módulos pertencentes a esta família. Emitido pelo materializer/exporter por conveniência do consumidor (evita scan); permitido apenas quando role=FAMILY."
+        },
+        "standalone_sellable": {
+          "type": "boolean",
+          "default": true,
+          "description": "Indica se um MODULE pode ser vendido isoladamente (true) ou apenas como parte de composição da família (false). Permitido apenas quando role=MODULE."
         }
       },
       "allOf": [
@@ -439,6 +476,105 @@
               }
             }
           }
+        },
+        {
+          "if": {
+            "properties": {
+              "role": {
+                "const": "MODULE"
+              }
+            },
+            "required": [
+              "role"
+            ]
+          },
+          "then": {
+            "required": [
+              "family_product_id"
+            ],
+            "not": {
+              "required": [
+                "member_product_ids"
+              ]
+            }
+          }
+        },
+        {
+          "if": {
+            "properties": {
+              "role": {
+                "const": "FAMILY"
+              }
+            },
+            "required": [
+              "role"
+            ]
+          },
+          "then": {
+            "not": {
+              "anyOf": [
+                {
+                  "required": [
+                    "family_product_id"
+                  ]
+                },
+                {
+                  "required": [
+                    "base_price"
+                  ]
+                },
+                {
+                  "required": [
+                    "standalone_sellable"
+                  ]
+                }
+              ]
+            }
+          }
+        },
+        {
+          "if": {
+            "anyOf": [
+              {
+                "properties": {
+                  "role": {
+                    "const": "STANDALONE"
+                  }
+                },
+                "required": [
+                  "role"
+                ]
+              },
+              {
+                "not": {
+                  "required": [
+                    "role"
+                  ]
+                }
+              }
+            ]
+          },
+          "then": {
+            "not": {
+              "anyOf": [
+                {
+                  "required": [
+                    "family_product_id"
+                  ]
+                },
+                {
+                  "required": [
+                    "member_product_ids"
+                  ]
+                },
+                {
+                  "required": [
+                    "standalone_sellable"
+                  ]
+                }
+              ]
+            }
+          }
         }
       ]
     },
@@ -1190,7 +1326,7 @@
         "position": {
           "type": "integer",
           "minimum": 0,
-          "description": "Ordem expl\u00edcita de exibi\u00e7\u00e3o; quando presente, consumidores DEVEM ordenar por position crescente."
+          "description": "Ordem explícita de exibição; quando presente, consumidores DEVEM ordenar por position crescente."
         },
         "type": {
           "type": "string",
@@ -1305,7 +1441,7 @@
           }
         }
       ],
-      "description": "Quantidade de insumo necess\u00e1ria. Aceita value fixo (number > 0) OU table_id (lookup). Sempre exige unit."
+      "description": "Quantidade de insumo necessária. Aceita value fixo (number > 0) OU table_id (lookup). Sempre exige unit."
     },
     "supplied_material_cost": {
       "type": "object",
@@ -1491,7 +1627,7 @@
           }
         }
       ],
-      "description": "Insumo consumido pelo produto, com regra de quem fornece (f\u00e1brica ou cliente). Ver se\u00e7\u00e3o 4.8 da spec."
+      "description": "Insumo consumido pelo produto, com regra de quem fornece (fábrica ou cliente). Ver seção 4.8 da spec."
     }
   }
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pacp/spec",
-  "version": "3.4.2",
+  "version": "3.6.0",
   "description": "PACP - Padrão Aberto de Catálogo e Precificação. Schema, profiles e validador para catálogos de produtos.",
   "type": "module",
   "main": "./dist/index.cjs",