@endevops/peppol-schema 0.1.3 → 0.1.4

package/src/schemas/fields/peppol-binary-object-schema.ts

@@ -1,14 +1,22 @@
 import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { peppolBase64Schema } from '#/schemas/utils/peppol-base-64-schema.ts';
-import { mimeCodesSchema } from '#/schemas/values/mime-codes-schema.ts';
+import { PeppolBase64 } from '#/schemas/utils/peppol-base-64-schema.ts';
+import { PeppolMimeCode } from '#/schemas/values/mime-codes-schema.ts';
 
 // RFC 4648 §5 — Base64url Encoding: URL/file-safe alphabet (A-Z a-z 0-9 - _), optional `=` padding.
 // Effect port of `z.base64url()`: keeps the value as a plain string and only validates the shape.
 const base64UrlSchema = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9\-_]+={0,2}$/)).annotate({ message: 'Invalid base64url' });
 
 /**
+ * @description An attached document embedded in the Invoice as a Base64 encoded binary object, together with its MIME type and file name. Wraps the
+ * `cbc:EmbeddedDocumentBinaryObject` element.
+ *
+ * @example
+ *   ```ts
+ *   { content: 'aHR0cHM6Ly90ZXN0LXZlZmEuZGlmaS5uby9wZXBwb2xiaXM=', mimeCode: 'text/csv', filename: 'Hours - spent.csv' }
+ *   ```;
+ *
  * @summary Binary object for attachments
  *
  * @name cbc:EmbeddedDocumentBinaryObject (+ @mimeCode, @filename)
@@ -25,7 +33,7 @@ export class PeppolBinaryObject extends opaque<PeppolBinaryObject>()(
      *
      * @name `#text` (Base64 content)
      */
-    content: Schema.Union([peppolBase64Schema, base64UrlSchema]),
+    content: Schema.Union([PeppolBase64, base64UrlSchema]),
     /**
      * @description The mime code of the attached document.
      *
@@ -36,7 +44,7 @@ export class PeppolBinaryObject extends opaque<PeppolBinaryObject>()(
      *
      * @name `@mimeCode`
      */
-    mimeCode: mimeCodesSchema,
+    mimeCode: PeppolMimeCode,
     /**
      * @description The file name of the attached document.
      *

package/src/schemas/fields/peppol-contact-schema.ts

@@ -2,6 +2,17 @@ import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description A contact point for a party, such as the person responsible for receiving the Invoice. Wraps the `cac:Contact` element with an optional name,
+ * telephone number and electronic mail address.
+ *
+ * @example
+ *   ```ts
+ *   { name: 'Lisa Johnson', telephone: '23434234', electronicMail: 'lj@buyer.se' }
+ *   ```;
+ *
+ * @see {@link PeppolPartySchema}
+ */
 export class PeppolContact extends opaque<PeppolContact>()(
   Schema.Struct({
     /**

package/src/schemas/fields/peppol-credit-note-line-schema.ts

@@ -3,7 +3,7 @@ import { Schema } from 'effect';
 import { PeppolBaseLine } from '#/schemas/fields/peppol-base-line-schema.ts';
 import { PeppolQuantity } from '#/schemas/fields/peppol-quantity-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { quantityUnitCodesSchema } from '#/schemas/values/quantity-unit-codes-schema.ts';
+import { PeppolQuantityUnitCode } from '#/schemas/values/quantity-unit-codes-schema.ts';
 
 /**
  * @description Credit note line is identical to Invoice line except the quantity element name.
@@ -35,10 +35,15 @@ export class PeppolCreditNoteLine extends opaque<PeppolCreditNoteLine>()(
            *
            * @see {@link quantityUnitCodes}
            */
-          unitCode: quantityUnitCodesSchema,
+          unitCode: PeppolQuantityUnitCode,
         })
       ),
     })
   )
 ) {}
+/**
+ * @description Encoded form of {@link PeppolCreditNoteLine} produced by the Effect Schema codec. Fields mirror the decoded structure.
+ *
+ * @see {@link PeppolCreditNoteLine}
+ */
 export interface PeppolCreditNoteLineEncoded extends Schema.Codec.Encoded<typeof PeppolCreditNoteLine> {}

package/src/schemas/fields/peppol-delivery-schema.ts

@@ -2,11 +2,21 @@ import { Schema } from 'effect';
 
 import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { icdCodesSchema } from '#/schemas/values/icd-codes-schema.ts';
+import { PeppolIcdCode } from '#/schemas/values/icd-codes-schema.ts';
 
 import { PeppolAddress } from './peppol-address-schema.ts';
 import { PeppolIdentifier } from './peppol-identifier-schema.ts';
 
+/**
+ * @description The name of the party to which the goods and services are delivered. Wraps the `cac:PartyName` element of the delivery party.
+ *
+ * @example
+ *   ```ts
+ *   { name: 'Delivery party Name' }
+ *   ```;
+ *
+ * @see {@link PeppolDeliveryParty}
+ */
 export class PeppolDeliveryPartyPartyName extends opaque<PeppolDeliveryPartyPartyName>()(
   Schema.Struct({
     /**
@@ -20,6 +30,16 @@ export class PeppolDeliveryPartyPartyName extends opaque<PeppolDeliveryPartyPart
   })
 ) {}
 
+/**
+ * @description The party to which the goods and services are delivered, when it differs from the Buyer. Wraps the `cac:DeliveryParty` element.
+ *
+ * @example
+ *   ```ts
+ *   { partyName: { name: 'Delivery party Name' } }
+ *   ```;
+ *
+ * @see {@link PeppolDelivery}
+ */
 export class PeppolDeliveryParty extends opaque<PeppolDeliveryParty>()(
   Schema.Struct({
     /**
@@ -31,6 +51,17 @@ export class PeppolDeliveryParty extends opaque<PeppolDeliveryParty>()(
   })
 ) {}
 
+/**
+ * @description The location at which the goods and services are delivered, identified by an identifier and an optional address. Wraps the `cac:DeliveryLocation`
+ * element.
+ *
+ * @example
+ *   ```ts
+ *   { id: { id: '9483759475923478', schemeId: '0088' }, address: { cityName: 'Stockholm', countryCode: { identificationCode: 'SE' } } }
+ *   ```;
+ *
+ * @see {@link PeppolDelivery}
+ */
 export class PeppolDeliveryLocation extends opaque<PeppolDeliveryLocation>()(
   Schema.Struct({
     /**
@@ -64,7 +95,7 @@ export class PeppolDeliveryLocation extends opaque<PeppolDeliveryLocation>()(
            *
            * @name `@schemeID`
            */
-          schemeId: Schema.optional(icdCodesSchema),
+          schemeId: Schema.optional(PeppolIcdCode),
         })
       )
     ),
@@ -79,6 +110,17 @@ export class PeppolDeliveryLocation extends opaque<PeppolDeliveryLocation>()(
   })
 ) {}
 
+/**
+ * @description Information about the delivery of the goods and services, such as the actual delivery date, the delivery location and the delivery party. Wraps the
+ * `cac:Delivery` element.
+ *
+ * @example
+ *   ```ts
+ *   { actualDeliveryDate: '2017-11-01', deliveryLocation: { id: { id: '9483759475923478' } } }
+ *   ```;
+ *
+ * @see {@link PeppolDeliveryLocation}
+ */
 export class PeppolDelivery extends opaque<PeppolDelivery>()(
   Schema.Struct({
     /**

package/src/schemas/fields/peppol-identifier-schema.ts

@@ -3,6 +3,14 @@ import { Schema } from 'effect';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
 /**
+ * @description A generic identifier paired with an optional identification scheme identifier. Wraps a `cbc:ID` element and its optional `@schemeID` attribute, and
+ * is reused across document references.
+ *
+ * @example
+ *   ```ts
+ *   { id: '99887766', schemeId: '0088' }
+ *   ```;
+ *
  * @summary Identifier with optional scheme
  *
  * @name `cbc:ID (+ optional @schemeID)`

package/src/schemas/fields/peppol-invoice-line-period-schema.ts

@@ -3,6 +3,17 @@ import { Schema } from 'effect';
 import { PeppolIsoDateString } from '#/schemas/peppol-iso-date-string.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description The period relevant for an Invoice line, given by an optional start date and end date. Wraps the `cac:InvoicePeriod` element as used on a line; the
+ * document level period extends this shape in {@link PeppolInvoicePeriod}.
+ *
+ * @example
+ *   ```ts
+ *   { startDate: '2017-10-01', endDate: '2017-10-31' }
+ *   ```;
+ *
+ * @see {@link PeppolInvoicePeriod}
+ */
 export class PeppolInvoiceLinePeriod extends opaque<PeppolInvoiceLinePeriod>()(
   Schema.Struct({
     /**

package/src/schemas/fields/peppol-invoice-line-schema.ts

@@ -3,9 +3,11 @@ import { Schema } from 'effect';
 import { PeppolBaseLine } from '#/schemas/fields/peppol-base-line-schema.ts';
 import { PeppolQuantity } from '#/schemas/fields/peppol-quantity-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { quantityUnitCodesSchema } from '#/schemas/values/quantity-unit-codes-schema.ts';
+import { PeppolQuantityUnitCode } from '#/schemas/values/quantity-unit-codes-schema.ts';
 
 /**
+ * @description A line of the Invoice, extending the common line fields with the invoiced quantity. Wraps the `cac:InvoiceLine` element.
+ *
  * @summary Invoice line
  *
  * @name cac:InvoiceLine
@@ -38,9 +40,14 @@ export class PeppolInvoiceLine extends opaque<PeppolInvoiceLine>()(
          *
          * @see {@link quantityUnitCodes}
          */
-        unitCode: quantityUnitCodesSchema,
+        unitCode: PeppolQuantityUnitCode,
       })
     ),
   })
 ) {}
+/**
+ * @description Encoded form of {@link PeppolInvoiceLine} produced by the Effect Schema codec. Fields mirror the decoded structure.
+ *
+ * @see {@link PeppolInvoiceLine}
+ */
 export interface PeppolInvoiceLineEncoded extends Schema.Codec.Encoded<typeof PeppolInvoiceLine> {}

package/src/schemas/fields/peppol-invoice-period-schema.ts

@@ -2,7 +2,7 @@ import { Schema } from 'effect';
 
 import { PeppolInvoiceLinePeriod } from '#/schemas/fields/peppol-invoice-line-period-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { vatDateCodeSchema } from '#/schemas/values/vat-date-code-schema.ts';
+import { PeppolVatDateCode } from '#/schemas/values/vat-date-code-schema.ts';
 
 /**
  * @description A group of business terms providing information on the invoice period. Also called delivery period. If the group is used, the invoiceing period
@@ -25,7 +25,7 @@ export class PeppolInvoicePeriod extends opaque<PeppolInvoicePeriod>()(
        *
        * @name `cbc:DescriptionCode`
        */
-      descriptionCode: Schema.optional(vatDateCodeSchema),
+      descriptionCode: Schema.optional(PeppolVatDateCode),
     })
   )
 ) {}

package/src/schemas/fields/peppol-item-classification-schema.ts

@@ -1,7 +1,7 @@
 import { Schema } from 'effect';
 
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { itemClassificationCodesSchema } from '#/schemas/values/item-classification-codes-schema.ts';
+import { PeppolItemClassificationCode } from '#/schemas/values/item-classification-codes-schema.ts';
 
 /**
  * @description A code for classifying the item by its type or nature.
@@ -30,7 +30,7 @@ export class PeppolItemClassification extends opaque<PeppolItemClassification>()
      *
      * @name `@listID`
      */
-    listId: itemClassificationCodesSchema,
+    listId: PeppolItemClassificationCode,
     /**
      * @description The identification scheme version identifier of the Item classification identifier.
      *

package/src/schemas/fields/peppol-line-allowance-charge-schema.ts

@@ -2,9 +2,20 @@ import { Schema } from 'effect';
 
 import { PriceAllowanceCharge } from '#/schemas/fields/peppol-line-price-allowance-charge-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { allowanceChargeReasonCodeSchema } from '#/schemas/values/allowance-charge-reason-code-schema.ts';
-import { chargeReasonCodeSchema } from '#/schemas/values/charge-reason-code-schema.ts';
+import { PeppolAllowanceChargeReasonCode } from '#/schemas/values/allowance-charge-reason-code-schema.ts';
+import { PeppolChargeReasonCode } from '#/schemas/values/charge-reason-code-schema.ts';
 
+/**
+ * @description Shared fields for an allowance or charge applied to an Invoice line. Extends the price level allowance and charge fields with the reason text and
+ * the multiplier factor used to calculate the amount.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 200, currencyId: 'EUR' }, chargeIndicator: false, allowanceChargeReason: 'Discount' }
+ *   ```;
+ *
+ * @see {@link PeppolLineAllowanceCharge}
+ */
 export class BaseLineAllowanceCharge extends opaque<BaseLineAllowanceCharge>()(
   Schema.Struct({
     ...PriceAllowanceCharge.fields /**
@@ -24,13 +35,24 @@ export class BaseLineAllowanceCharge extends opaque<BaseLineAllowanceCharge>()(
   })
 ) {}
 
+/**
+ * @description An allowance applied to an Invoice line, marked by a `cbc:ChargeIndicator` of `false`. Adds an allowance reason code to the shared line allowance
+ * and charge fields.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 200, currencyId: 'EUR' }, chargeIndicator: false, allowanceChargeReasonCode: '95' }
+ *   ```;
+ *
+ * @see {@link PeppolLineAllowanceCharge}
+ */
 export class PeppolLineAllowance extends opaque<PeppolLineAllowance>()(
   Schema.Struct({
     ...BaseLineAllowanceCharge.fields,
     /**
      * @name cbc:AllowanceChargeReasonCode
      */
-    allowanceChargeReasonCode: Schema.optional(allowanceChargeReasonCodeSchema),
+    allowanceChargeReasonCode: Schema.optional(PeppolAllowanceChargeReasonCode),
     /**
      * @name cbc:ChargeIndicator
      *
@@ -42,13 +64,24 @@ export class PeppolLineAllowance extends opaque<PeppolLineAllowance>()(
   })
 ) {}
 
+/**
+ * @description A charge applied to an Invoice line, marked by a `cbc:ChargeIndicator` of `true`. Adds a charge reason code to the shared line allowance and charge
+ * fields.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 25, currencyId: 'EUR' }, chargeIndicator: true, allowanceChargeReasonCode: 'AA' }
+ *   ```;
+ *
+ * @see {@link PeppolLineAllowanceCharge}
+ */
 export class PeppolLineCharge extends opaque<PeppolLineCharge>()(
   Schema.Struct({
     ...BaseLineAllowanceCharge.fields,
     /**
      * @name cbc:AllowanceChargeReasonCode
      */
-    allowanceChargeReasonCode: Schema.optional(chargeReasonCodeSchema),
+    allowanceChargeReasonCode: Schema.optional(PeppolChargeReasonCode),
     /**
      * @name cbc:ChargeIndicator
      *
@@ -60,9 +93,24 @@ export class PeppolLineCharge extends opaque<PeppolLineCharge>()(
   })
 ) {}
 
-export const peppolLineAllowanceChargeSchema = Schema.Union([PeppolLineAllowance, PeppolLineCharge]).annotate({
-  message: 'unable to decode line allowance charge',
-});
+/**
+ * @description An allowance or charge applied to an Invoice line, selected by the `cbc:ChargeIndicator` value: `false` selects an allowance, `true` selects a
+ * charge.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 25, currencyId: 'EUR' }, chargeIndicator: true, allowanceChargeReasonCode: 'AA', allowanceChargeReason: 'Advertising' }
+ *   ```;
+ *
+ * @see {@link PeppolLineAllowance}
+ */
+export class PeppolLineAllowanceCharge extends opaque<PeppolLineAllowanceCharge>()(
+  Schema.Union([PeppolLineAllowance, PeppolLineCharge]).annotate({ message: 'unable to decode line allowance charge' })
+) {}
 
-export type PeppolLineAllowanceCharge = typeof peppolLineAllowanceChargeSchema.Type;
-export type PeppolLineAllowanceChargeEncoded = typeof peppolLineAllowanceChargeSchema.Encoded;
+/**
+ * @description Encoded form of {@link PeppolLineAllowanceCharge} produced by the Effect Schema codec.
+ *
+ * @see {@link PeppolLineAllowanceCharge}
+ */
+export type PeppolLineAllowanceChargeEncoded = Schema.Codec.Encoded<typeof PeppolLineAllowanceCharge>;

package/src/schemas/fields/peppol-line-item-schema.ts

@@ -4,9 +4,19 @@ import { PeppolIdentifier } from '#/schemas/fields/peppol-identifier-schema.ts';
 import { PeppolItemClassification } from '#/schemas/fields/peppol-item-classification-schema.ts';
 import { PeppolTaxCategory } from '#/schemas/fields/peppol-tax-category-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { icdCodesSchema } from '#/schemas/values/icd-codes-schema.ts';
-import { peppolCountryCodeSchema } from '#/schemas/values/peppol-country-code-schema.ts';
+import { PeppolIcdCode } from '#/schemas/values/icd-codes-schema.ts';
+import { PeppolCountryCodeValue } from '#/schemas/values/peppol-country-code-schema.ts';
 
+/**
+ * @description An additional property of the item, expressed as an attribute name and value pair.
+ *
+ * @example
+ *   ```ts
+ *   { name: 'Colour', value: 'Blue' }
+ *   ```;
+ *
+ * @see {@link PeppolLineItem}
+ */
 export class PeppolAdditionalItemProperties extends opaque<PeppolAdditionalItemProperties>()(
   Schema.Struct({
     /**
@@ -28,6 +38,16 @@ export class PeppolAdditionalItemProperties extends opaque<PeppolAdditionalItemP
   })
 ) {}
 
+/**
+ * @description A code classifying the item by its type or nature, identified by a scheme such as CPV.
+ *
+ * @example
+ *   ```ts
+ *   { itemClassification: { id: '09348023', listId: 'STI' } }
+ *   ```;
+ *
+ * @see {@link PeppolItemClassification}
+ */
 export class PeppolCommodityClassifications extends opaque<PeppolCommodityClassifications>()(
   Schema.Struct({
     /**
@@ -44,6 +64,16 @@ export class PeppolCommodityClassifications extends opaque<PeppolCommodityClassi
   })
 ) {}
 
+/**
+ * @description The country from which the item originates, identified by an ISO 3166-1 country code.
+ *
+ * @example
+ *   ```ts
+ *   { identificationCode: 'NO' }
+ *   ```;
+ *
+ * @see {@link PeppolLineItem}
+ */
 export class PeppolOriginCountryCode extends opaque<PeppolOriginCountryCode>()(
   Schema.Struct({
     /**
@@ -53,10 +83,20 @@ export class PeppolOriginCountryCode extends opaque<PeppolOriginCountryCode>()(
      *
      * @name `cbc:IdentificationCode`
      */
-    identificationCode: peppolCountryCodeSchema,
+    identificationCode: PeppolCountryCodeValue,
   })
 ) {}
 
+/**
+ * @description An item identifier based on a registered scheme, such as a GTIN or EAN.
+ *
+ * @example
+ *   ```ts
+ *   { id: { id: '21382183120983', schemeId: '0088' } }
+ *   ```;
+ *
+ * @see {@link PeppolIdentifier}
+ */
 export class PeppolStandardItemIdentification extends opaque<PeppolStandardItemIdentification>()(
   Schema.Struct({
     /**
@@ -83,12 +123,22 @@ export class PeppolStandardItemIdentification extends opaque<PeppolStandardItemI
          *
          * @name `@schemeID`
          */
-        schemeId: icdCodesSchema,
+        schemeId: PeppolIcdCode,
       })
     ),
   })
 ) {}
 
+/**
+ * @description An identifier assigned by the Seller for the item.
+ *
+ * @example
+ *   ```ts
+ *   { id: '987323' }
+ *   ```;
+ *
+ * @see {@link PeppolLineItem}
+ */
 export class PeppolSellersItemIdentification extends opaque<PeppolSellersItemIdentification>()(
   Schema.Struct({
     /**
@@ -105,6 +155,16 @@ export class PeppolSellersItemIdentification extends opaque<PeppolSellersItemIde
   })
 ) {}
 
+/**
+ * @description An identifier assigned by the Buyer for the item.
+ *
+ * @example
+ *   ```ts
+ *   { id: '12345' }
+ *   ```;
+ *
+ * @see {@link PeppolLineItem}
+ */
 export class PeppolBuyersItemIdentification extends opaque<PeppolBuyersItemIdentification>()(
   Schema.Struct({
     /**
@@ -122,6 +182,8 @@ export class PeppolBuyersItemIdentification extends opaque<PeppolBuyersItemIdent
 ) {}
 
 /**
+ * @description The item details for an invoice or credit note line, including its name, identifiers, classification, and line VAT category.
+ *
  * @summary Item details on invoice/credit-note line
  *
  * @name cac:Item
@@ -193,4 +255,7 @@ export class PeppolLineItem extends opaque<PeppolLineItem>()(
   })
 ) {}
 
+/**
+ * @description Alias for {@link PeppolLineItem}.
+ */
 export type PeppolItem = PeppolLineItem;

package/src/schemas/fields/peppol-line-price-allowance-charge-schema.ts

@@ -3,6 +3,16 @@ import { Schema } from 'effect';
 import { PeppolAmount } from '#/schemas/fields/peppol-amount-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description A price level allowance or charge applied to the item price, expressed as an amount and a charge indicator.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 200, currencyId: 'EUR' }, chargeIndicator: false }
+ *   ```;
+ *
+ * @see {@link PeppolLinePriceAllowanceCharge}
+ */
 class PriceAllowanceCharge extends opaque<PriceAllowanceCharge>()(
   Schema.Struct({
     /**
@@ -28,6 +38,16 @@ class PriceAllowanceCharge extends opaque<PriceAllowanceCharge>()(
   })
 ) {}
 
+/**
+ * @description A price level allowance on the item price. Only allowances are allowed at price level, so the charge indicator is fixed to false.
+ *
+ * @example
+ *   ```ts
+ *   { amount: { value: 200, currencyId: 'EUR' }, chargeIndicator: false }
+ *   ```;
+ *
+ * @see {@link PeppolLinePrice}
+ */
 export class PeppolLinePriceAllowanceCharge extends opaque<PeppolLinePriceAllowanceCharge>()(
   PriceAllowanceCharge.pipe(
     Schema.fieldsAssign({

package/src/schemas/fields/peppol-line-price-schema.ts

@@ -6,6 +6,8 @@ import { PeppolQuantity } from '#/schemas/fields/peppol-quantity-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
 /**
+ * @description The price details of an invoice or credit note line, including the price amount and any price level allowance.
+ *
  * @summary Price details on invoice line
  *
  * @name cac:Price

package/src/schemas/fields/peppol-order-reference-schema.ts

@@ -3,6 +3,8 @@ import { Schema } from 'effect';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
 /**
+ * @description A reference to the purchase order or sales order that the invoice relates to.
+ *
  * @summary ORDER AND SALES ORDER REFERENCE
  *
  * @name cac:OrderReference

package/src/schemas/fields/peppol-party-base-schema.ts

@@ -6,9 +6,19 @@ import { PeppolIdentifier } from '#/schemas/fields/peppol-identifier-schema.ts';
 import { PeppolPartyLegalEntity } from '#/schemas/fields/peppol-party-legal-entity-schema.ts';
 import { PeppolPartyTaxScheme } from '#/schemas/fields/peppol-party-tax-scheme-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
-import { electronicCodesSchema } from '#/schemas/values/electronic-codes-schema.ts';
-import { icdCodesSchema } from '#/schemas/values/icd-codes-schema.ts';
+import { PeppolElectronicAddressCode } from '#/schemas/values/electronic-codes-schema.ts';
+import { PeppolIcdCode } from '#/schemas/values/icd-codes-schema.ts';
 
+/**
+ * @description A name by which the Buyer or Seller is known, other than its registered name.
+ *
+ * @example
+ *   ```ts
+ *   { name: 'SupplierTradingName Ltd.' }
+ *   ```;
+ *
+ * @see {@link PeppolPartySchema}
+ */
 export class PeppolPartyName extends opaque<PeppolPartyName>()(
   Schema.Struct({
     /**
@@ -23,6 +33,16 @@ export class PeppolPartyName extends opaque<PeppolPartyName>()(
   })
 ) {}
 
+/**
+ * @description An identifier of the Buyer or Seller, with an optional identification scheme.
+ *
+ * @example
+ *   ```ts
+ *   { id: { id: '99887766', schemeId: '0088' } }
+ *   ```;
+ *
+ * @see {@link PeppolPartySchema}
+ */
 export class PeppolPartyIdentification extends opaque<PeppolPartyIdentification>()(
   Schema.Struct({
     /**
@@ -52,12 +72,22 @@ export class PeppolPartyIdentification extends opaque<PeppolPartyIdentification>
          *
          * @name `@schemeID`
          */
-        schemeId: Schema.optional(icdCodesSchema),
+        schemeId: Schema.optional(PeppolIcdCode),
       })
     ),
   })
 ) {}
 
+/**
+ * @description The Buyer or Seller electronic address to which the application level response to the invoice may be delivered.
+ *
+ * @example
+ *   ```ts
+ *   { id: '9482348239847239874', schemeId: '0088' }
+ *   ```;
+ *
+ * @see {@link PeppolPartySchema}
+ */
 export class PeppolPartyEndpointId extends opaque<PeppolPartyEndpointId>()(
   PeppolIdentifier.pipe(
     Schema.fieldsAssign({
@@ -79,12 +109,14 @@ export class PeppolPartyEndpointId extends opaque<PeppolPartyEndpointId>()(
        *
        * @name `@schemeID`
        */
-      schemeId: electronicCodesSchema,
+      schemeId: PeppolElectronicAddressCode,
     })
   )
 ) {}
 
 /**
+ * @description The common party substructure shared by the supplier, customer, and other party roles.
+ *
  * @summary Party common substructure
  *
  * @name cac:Party

package/src/schemas/fields/peppol-party-legal-entity-schema.ts

@@ -3,6 +3,16 @@ import { Schema } from 'effect';
 import { PeppolIdentifier } from '#/schemas/fields/peppol-identifier-schema.ts';
 import { opaque } from '#/schemas/utils/opaque.ts';
 
+/**
+ * @description The legal entity details of a party, including the registered name and optional company identifiers.
+ *
+ * @example
+ *   ```ts
+ *   { registrationName: 'SupplierOfficialName Ltd', companyId: { id: 'GB983294' } }
+ *   ```;
+ *
+ * @see {@link PeppolPartySchema}
+ */
 export class PeppolPartyLegalEntity extends opaque<PeppolPartyLegalEntity>()(
   Schema.Struct({
     /**
@@ -29,4 +39,7 @@ export class PeppolPartyLegalEntity extends opaque<PeppolPartyLegalEntity>()(
   })
 ) {}
 
+/**
+ * @description Alias for {@link PeppolPartyLegalEntity}.
+ */
 export type PeppolPartyLegalEntitySchema = PeppolPartyLegalEntity;