$id: "https://schema.nfh.global/EnergyGift/v0.3"
$schema: "https://json-schema.org/draft/2020-12/schema"
title: EnergyGift
description: >
  Gift parameters for P2P energy gifting. Enables a prosumer (gifter) to make an
  energy offer available at 0 price on the catalog, discoverable by the SHA-256 hash
  of the recipient's phone number and claimable via a secret shared out-of-band
  from the gifter to the recipient.

  This is the v0.3 schema, originally defined as a component in EnergyTrade/v0.3/attributes.yaml.
x-tags:
  - energy-trade
  - p2p-trading
  - gifting
type: object
additionalProperties: false
required: [lookupHash, claimVerifier, expiresAt]
x-jsonld:
  "@context": ./context.jsonld
  "@type": EnergyGift
properties:

  lookupHash:
    type: string
    pattern: '^[A-Fa-f0-9]{64}$'
    description: >
      SHA-256 hash of the recipient's phone number (E.164 format, e.g. +919876543210).
      Used for privacy-preserving discovery — the catalog can be searched by this hash
      so that only the intended recipient finds the gift offer.
    example: "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
    x-jsonld:
      "@id": lookupHash

  claimVerifier:
    type: string
    pattern: '^[A-Fa-f0-9]{64}$'
    description: >
      SHA-256 hash of a claim secret shared out-of-band from the gifter to the
      recipient. The recipient proves ownership by presenting the pre-image (the
      original secret) which is hashed and compared to this value during claim
      validation.
    example: "f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5d4c3b2a1f6e5"
    x-jsonld:
      "@id": claimVerifier

  expiresAt:
    type: string
    format: date-time
    pattern: '^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$'
    description: >
      Gift expiration timestamp in UTC (ISO 8601 with Z suffix). After this time
      the gift offer is no longer claimable and may be removed from the catalog.
    example: "2025-07-01T00:00:00Z"
    x-jsonld:
      "@id": expiresAt