<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
           targetNamespace="urn:hdt-af:research:experiment:1.0"
           xmlns:tns="urn:hdt-af:research:experiment:1.0"
           elementFormDefault="qualified">

  <!--
    Schema canônico para especificação de experimentos federados no HDT-AF.
    Cada experimento deve ter um arquivo research.xml validado por este schema.
    Versão: 1.0  |  Projeto: HDT-AF (Hyperledger Digital Twin — Aprendizagem Federada)
  -->

  <!-- ═══════════════════════════════════════════════════════════════ ROOT -->
  <xs:element name="experiment" type="tns:ExperimentType"/>

  <!-- ═══════════════════════════════════════════════════════════ TOP LEVEL -->
  <xs:complexType name="ExperimentType">
    <xs:all>
      <xs:element name="identity"      type="tns:IdentityType"/>
      <xs:element name="dataset"       type="tns:DatasetType"/>
      <xs:element name="model"         type="tns:ModelType"/>
      <xs:element name="orchestration" type="tns:OrchestrationType"/>
      <xs:element name="outputs"       type="tns:OutputsType"/>
      <xs:element name="lgpd"          type="tns:LgpdType"/>
      <xs:element name="execution"     type="tns:ExecutionType"/>
    </xs:all>
    <xs:attribute name="schemaVersion" type="xs:string" use="required"/>
  </xs:complexType>

  <!-- ══════════════════════════════════════════════════════════ IDENTITY -->
  <xs:complexType name="IdentityType">
    <xs:all>
      <xs:element name="experimentId"    type="xs:string"/>
      <xs:element name="contractVersion" type="xs:string"/>
      <xs:element name="title"           type="xs:string"/>
      <xs:element name="coordinatorId"   type="xs:string"/>
      <xs:element name="taskType"        type="tns:TaskTypeEnum"/>
      <xs:element name="targetVariable"  type="xs:string"/>
      <xs:element name="status"          type="tns:ContractStatusEnum"/>
      <!--
        Texto do contrato de consentimento que o cliente (participante/dispositivo)
        deve aceitar antes de participar do experimento federado.
        Deve ser redigido em linguagem acessível (LGPD Art. 9, VI).
        O hash SHA-256 deste texto é registrado on-chain no Hyperledger Fabric
        como evidência de que o cliente aceitou exatamente esta versão.
      -->
      <xs:element name="consentContract" type="tns:ConsentContractType" minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <xs:complexType name="ConsentContractType">
    <xs:all>
      <!-- Título exibido ao cliente na tela de aceite -->
      <xs:element name="title"       type="xs:string"/>
      <!-- Versão do documento de consentimento (pode diferir da contractVersion) -->
      <xs:element name="docVersion"  type="xs:string"/>
      <!-- Data de vigência: a partir de quando este texto é válido -->
      <xs:element name="validFrom"   type="xs:date"/>
      <!-- Texto completo do termo em linguagem acessível (LGPD Art. 9, VI) -->
      <xs:element name="body"        type="xs:string"/>
      <!-- Direitos do titular listados explicitamente (LGPD Art. 18) -->
      <xs:element name="rights"      type="tns:StringListType" minOccurs="0"/>
      <!-- Contato do controlador de dados para exercício dos direitos -->
      <xs:element name="controller"  type="tns:ControllerType" minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <xs:complexType name="ControllerType">
    <xs:all>
      <xs:element name="name"        type="xs:string"/>
      <xs:element name="institution" type="xs:string" minOccurs="0"/>
      <xs:element name="contact"     type="xs:string" minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <xs:simpleType name="TaskTypeEnum">
    <xs:restriction base="xs:string">
      <xs:enumeration value="binary_classification"/>
      <xs:enumeration value="multiclass_classification"/>
      <xs:enumeration value="regression"/>
      <xs:enumeration value="anomaly_detection"/>
      <xs:enumeration value="time_series_forecasting"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="ContractStatusEnum">
    <xs:restriction base="xs:string">
      <xs:enumeration value="DRAFT"/>
      <xs:enumeration value="PUBLISHED"/>
      <xs:enumeration value="ACTIVE"/>
      <xs:enumeration value="CLOSED"/>
      <xs:enumeration value="REVOKED"/>
    </xs:restriction>
  </xs:simpleType>

  <!-- ══════════════════════════════════════════════════════════ DATASET -->
  <xs:complexType name="DatasetType">
    <xs:all>
      <xs:element name="source"        type="tns:DatasetSourceType"/>
      <xs:element name="partitioning"  type="tns:PartitioningType"/>
      <xs:element name="schema"        type="tns:DataSchemaType"/>
      <xs:element name="evaluation"    type="tns:EvaluationDatasetType" minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <xs:complexType name="DatasetSourceType">
    <xs:all>
      <!-- Identificação básica -->
      <xs:element name="name"          type="xs:string"/>
      <xs:element name="origin"        type="xs:string" minOccurs="0"/>
      <xs:element name="url"           type="xs:anyURI" minOccurs="0"/>
      <xs:element name="license"       type="xs:string" minOccurs="0"/>
      <xs:element name="syntheticData" type="xs:boolean"/>

      <!-- Descrição geral do domínio e contexto clínico/científico -->
      <xs:element name="description"   type="xs:string" minOccurs="0"/>

      <!-- Estatísticas do dataset -->
      <xs:element name="totalSamples"  type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="dimensions"    type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="classDistribution" type="tns:ClassDistributionType" minOccurs="0"/>
      <xs:element name="classes"       type="tns:ClassListType" minOccurs="0"/>

      <!-- Especificação técnica do sinal (sensores, séries temporais, imagens) -->
      <xs:element name="signalSpec"    type="tns:SignalSpecType" minOccurs="0"/>

      <!-- Protocolo de coleta / aquisição -->
      <xs:element name="acquisition"   type="tns:AcquisitionType" minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <!-- Distribuição de classes no dataset -->
  <xs:complexType name="ClassDistributionType">
    <xs:sequence>
      <xs:element name="classCount" maxOccurs="unbounded">
        <xs:complexType>
          <xs:attribute name="id"      type="xs:string"  use="required"/>
          <xs:attribute name="label"   type="xs:string"/>
          <xs:attribute name="count"   type="xs:nonNegativeInteger"/>
          <xs:attribute name="percent" type="xs:decimal"/>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <!-- Especificação técnica do sinal bruto -->
  <xs:complexType name="SignalSpecType">
    <xs:all>
      <xs:element name="type"               type="xs:string" minOccurs="0"/>
      <!-- ex: ECG, accelerometer, gyroscope, industrial_telemetry -->
      <xs:element name="samplingFrequency"  type="xs:string" minOccurs="0"/>
      <!-- ex: "360 Hz", "50 Hz", "N/A" -->
      <xs:element name="samplesPerInstance" type="xs:positiveInteger" minOccurs="0"/>
      <!-- pontos temporais por amostra/janela/batimento -->
      <xs:element name="unit"               type="xs:string" minOccurs="0"/>
      <!-- ex: "mV", "m/s²", "rad/s", "bar" -->
      <xs:element name="leads"              type="xs:string" minOccurs="0"/>
      <!-- derivações ECG: "Lead II", "V5", etc. -->
      <xs:element name="windowDuration"     type="xs:string" minOccurs="0"/>
      <!-- duração de cada janela/batimento: "~0.88 s", "2.56 s" -->
      <xs:element name="normalization"      type="xs:string" minOccurs="0"/>
      <!-- método de normalização aplicado -->
      <xs:element name="segmentation"       type="xs:string" minOccurs="0"/>
      <!-- como instâncias foram extraídas do sinal contínuo -->
      <xs:element name="featureEngineering" type="xs:string" minOccurs="0"/>
      <!-- transformações aplicadas: FFT, wavelets, estatísticas, etc. -->
      <xs:element name="clinicalRelevance"  type="xs:string" minOccurs="0"/>
      <!-- significado clínico/científico das features -->
    </xs:all>
  </xs:complexType>

  <!-- Protocolo de aquisição e contexto experimental -->
  <xs:complexType name="AcquisitionType">
    <xs:all>
      <xs:element name="equipment"    type="xs:string" minOccurs="0"/>
      <!-- equipamento ou sensor usado na coleta -->
      <xs:element name="subjects"     type="xs:string" minOccurs="0"/>
      <!-- perfil dos participantes/pacientes -->
      <xs:element name="environment"  type="xs:string" minOccurs="0"/>
      <!-- ambiente de coleta: clínica, campo, laboratório -->
      <xs:element name="protocol"     type="xs:string" minOccurs="0"/>
      <!-- protocolo experimental: atividades, condições clínicas -->
      <xs:element name="annotation"   type="xs:string" minOccurs="0"/>
      <!-- como os rótulos foram atribuídos: especialista, algoritmo -->
      <xs:element name="splitStrategy" type="xs:string" minOccurs="0"/>
      <!-- como treino/teste foram definidos originalmente -->
    </xs:all>
  </xs:complexType>

  <xs:complexType name="ClassListType">
    <xs:sequence>
      <xs:element name="class" maxOccurs="unbounded">
        <xs:complexType>
          <xs:simpleContent>
            <xs:extension base="xs:string">
              <xs:attribute name="id"    type="xs:string" use="required"/>
              <xs:attribute name="label" type="xs:string"/>
            </xs:extension>
          </xs:simpleContent>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="PartitioningType">
    <xs:all>
      <xs:element name="strategy"    type="xs:string"/>
      <xs:element name="description" type="xs:string" minOccurs="0"/>
      <xs:element name="numClients"  type="xs:positiveInteger"/>
      <xs:element name="trainSplit"  type="xs:string" minOccurs="0"/>
      <xs:element name="testSplit"   type="xs:string" minOccurs="0"/>
      <xs:element name="localPath"   type="xs:string" minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <xs:complexType name="DataSchemaType">
    <xs:all>
      <xs:element name="sourceModel"      type="xs:string"/>
      <xs:element name="fields"           type="tns:FieldListType"/>
<xs:element name="completenessMin"  type="xs:decimal" minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <xs:complexType name="FieldListType">
    <xs:sequence>
      <xs:element name="field" maxOccurs="unbounded">
        <xs:complexType>
          <xs:attribute name="name" type="xs:string" use="required"/>
          <xs:attribute name="type" type="xs:string" use="required"/>
          <xs:attribute name="role" use="required">
            <xs:simpleType>
              <xs:restriction base="xs:string">
                <xs:enumeration value="feature"/>
                <xs:enumeration value="target"/>
                <xs:enumeration value="identifier"/>
                <xs:enumeration value="metadata"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:attribute>
          <xs:attribute name="unit"     type="xs:string"/>
          <xs:attribute name="required" type="xs:boolean"/>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <xs:complexType name="EvaluationDatasetType">
    <xs:all>
      <xs:element name="datasetId"           type="xs:string"/>
      <xs:element name="ownerId"             type="xs:string"/>
      <xs:element name="uri"                 type="xs:string"/>
      <xs:element name="metricName"          type="xs:string"/>
      <xs:element name="distributionPolicy"  type="xs:string"/>
      <xs:element name="evaluateClientModels" type="xs:boolean"/>
      <xs:element name="evaluateGlobalModel"  type="xs:boolean"/>
    </xs:all>
  </xs:complexType>

  <!-- ══════════════════════════════════════════════════════════ MODEL -->
  <xs:complexType name="ModelType">
    <xs:all>
      <xs:element name="algorithmId"        type="xs:string"/>
      <xs:element name="algorithmFamily"    type="xs:string" minOccurs="0"/>
      <xs:element name="updateFormat"       type="xs:string"/>
      <xs:element name="totalParameters"    type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="architecture"       type="tns:ArchitectureType" minOccurs="0"/>
      <xs:element name="hyperparameters"    type="tns:HyperparametersType"/>
      <xs:element name="supportedTargets"   type="tns:StringListType"/>
    </xs:all>
  </xs:complexType>

  <xs:complexType name="ArchitectureType">
    <xs:all>
      <xs:element name="type"      type="xs:string"/>
      <xs:element name="optimizer" type="xs:string"/>
      <xs:element name="loss"      type="xs:string"/>
      <xs:element name="layers" minOccurs="0">
        <xs:complexType>
          <xs:sequence>
            <xs:element name="layer" maxOccurs="unbounded">
              <xs:complexType>
                <xs:attribute name="name"       type="xs:string" use="required"/>
                <xs:attribute name="size"       type="xs:positiveInteger"/>
                <xs:attribute name="activation" type="xs:string"/>
              </xs:complexType>
            </xs:element>
          </xs:sequence>
        </xs:complexType>
      </xs:element>
    </xs:all>
  </xs:complexType>

  <xs:complexType name="HyperparametersType">
    <xs:sequence>
      <xs:element name="param" maxOccurs="unbounded">
        <xs:complexType>
          <xs:simpleContent>
            <xs:extension base="xs:string">
              <xs:attribute name="name" type="xs:string" use="required"/>
            </xs:extension>
          </xs:simpleContent>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <!-- ═══════════════════════════════════════════════ ORCHESTRATION -->
  <!--
    As três dimensões declaráveis no ExperimentContract após o refactoring:
      - participation: QUEM pode participar
      - schedule:      QUANDO (início, acompanhamento, fim)
      - aggregation:   COMO (mecânica de agregação e segurança)
  -->
  <xs:complexType name="OrchestrationType">
    <xs:all>
      <xs:element name="participation" type="tns:ParticipationType"/>
      <xs:element name="schedule"      type="tns:ScheduleType"/>
      <xs:element name="aggregation"   type="tns:AggregationType"/>
      <xs:element name="privacy"       type="tns:PrivacyType"/>
    </xs:all>
  </xs:complexType>

  <!-- QUEM -->
  <xs:complexType name="ParticipationType">
    <xs:all>
      <xs:element name="selectionStrategy"  type="tns:SelectionStrategyEnum"/>
      <xs:element name="samplingFraction"   type="xs:decimal"  minOccurs="0"/>
      <xs:element name="minimumClients"     type="xs:nonNegativeInteger"/>
      <xs:element name="nonResponsivePolicy" type="tns:NonResponsivePolicyEnum"/>
      <xs:element name="eligibleClientIds"  type="tns:StringListType" minOccurs="0"/>
      <xs:element name="rationale"          type="xs:string" minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <xs:simpleType name="SelectionStrategyEnum">
    <xs:restriction base="xs:string">
      <xs:enumeration value="all_accepted"/>
      <xs:enumeration value="random_sampled"/>
      <xs:enumeration value="round_robin"/>
    </xs:restriction>
  </xs:simpleType>

  <xs:simpleType name="NonResponsivePolicyEnum">
    <xs:restriction base="xs:string">
      <xs:enumeration value="PROCEED_WITH_AVAILABLE"/>
      <xs:enumeration value="REQUIRE_FULL_PARTICIPATION"/>
      <xs:enumeration value="REQUIRE_QUORUM_OF_SELECTED"/>
    </xs:restriction>
  </xs:simpleType>

  <!-- QUANDO -->
  <xs:complexType name="ScheduleType">
    <xs:all>
      <xs:element name="roundTimeoutSeconds"  type="xs:positiveInteger"/>
      <xs:element name="maxRounds"            type="xs:nonNegativeInteger"/>
      <xs:element name="terminationCondition" type="tns:TerminationConditionEnum"/>
      <xs:element name="scheduledStart"       type="xs:dateTime" minOccurs="0"/>
      <xs:element name="monitoringNotes"      type="xs:string"   minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <xs:simpleType name="TerminationConditionEnum">
    <xs:restriction base="xs:string">
      <xs:enumeration value="MANUAL"/>
      <xs:enumeration value="MAX_ROUNDS"/>
    </xs:restriction>
  </xs:simpleType>

  <!-- COMO — agregação -->
  <xs:complexType name="AggregationType">
    <xs:all>
      <xs:element name="strategy"           type="xs:string"/>
      <xs:element name="minimumClients"     type="xs:positiveInteger"/>
      <xs:element name="minimumExamples"    type="xs:positiveInteger"/>
      <xs:element name="maxClientWeight"    type="xs:decimal"/>
      <xs:element name="minClientWeight"    type="xs:decimal"/>
      <xs:element name="maxUpdateNorm"      type="xs:decimal"/>
      <xs:element name="clippingEnabled"    type="xs:boolean"/>
    </xs:all>
  </xs:complexType>

  <!-- COMO — privacidade -->
  <xs:complexType name="PrivacyType">
    <xs:all>
      <xs:element name="differentialPrivacy" type="xs:boolean"/>
      <xs:element name="epsilon"             type="xs:decimal" minOccurs="0"/>
      <xs:element name="noiseMultiplier"     type="xs:decimal" minOccurs="0"/>
      <!--
        Norma L2 maxima do vetor de update (clip) antes do ruido gaussiano — parametro C
        do DP-SGD (Abadi et al., CCS 2016). Ausente/omitido usa o default operacional do
        gerenciador de dados (DataComponent), documentado como 1.0. Adicionado no BL-081 —
        antes disso, cada experimento hardcoded o proprio clipNorm em codigo Java.
      -->
      <xs:element name="clippingNorm"        type="xs:decimal" minOccurs="0"/>
      <xs:element name="secureAggregation"   type="xs:boolean"/>
      <xs:element name="maxRoundsPerClient"  type="xs:positiveInteger" minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <!-- ══════════════════════════════════════════════════════════ OUTPUTS -->
  <xs:complexType name="OutputsType">
    <xs:all>
      <xs:element name="files"           type="tns:StringListType"/>
      <xs:element name="allowedMetrics"  type="tns:StringListType"/>
      <xs:element name="prohibited"      type="tns:StringListType" minOccurs="0"/>
      <xs:element name="maxSizeBytes"    type="xs:long" minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <!-- ════════════════════════════════════════════════════════════ LGPD -->
  <xs:complexType name="LgpdType">
    <xs:all>
      <xs:element name="legalBasis"           type="xs:string"/>
      <xs:element name="dataCategory"         type="tns:DataCategoryEnum"/>
      <xs:element name="pseudonymizationSalt" type="xs:string" minOccurs="0"/>
      <xs:element name="retentionDays"        type="xs:positiveInteger" minOccurs="0"/>
      <xs:element name="notes"                type="xs:string" minOccurs="0"/>
    </xs:all>
  </xs:complexType>

  <xs:simpleType name="DataCategoryEnum">
    <xs:restriction base="xs:string">
      <xs:enumeration value="general"/>
      <xs:enumeration value="sensitive_health"/>
      <xs:enumeration value="sensitive_biometric"/>
      <xs:enumeration value="behavioral"/>
      <xs:enumeration value="industrial_telemetry"/>
    </xs:restriction>
  </xs:simpleType>

  <!-- ══════════════════════════════════════════════════════ EXECUTION -->
  <xs:complexType name="ExecutionType">
    <xs:all>
      <xs:element name="entrypoint"    type="xs:string"/>
      <xs:element name="runtime"       type="tns:RuntimeType"/>
      <xs:element name="scripts"       type="tns:ScriptsType"/>
      <xs:element name="networkPolicy" type="xs:string"/>
      <xs:element name="fsPolicy"      type="xs:string"/>
    </xs:all>
  </xs:complexType>

  <xs:complexType name="RuntimeType">
    <xs:all>
      <xs:element name="language"  type="xs:string"/>
      <xs:element name="version"   type="xs:string"/>
      <xs:element name="buildFile" type="xs:string"/>
    </xs:all>
  </xs:complexType>

  <xs:complexType name="ScriptsType">
    <xs:sequence>
      <xs:element name="script" maxOccurs="unbounded">
        <xs:complexType>
          <xs:simpleContent>
            <xs:extension base="xs:string">
              <xs:attribute name="name"        type="xs:string" use="required"/>
              <xs:attribute name="description" type="xs:string"/>
            </xs:extension>
          </xs:simpleContent>
        </xs:complexType>
      </xs:element>
    </xs:sequence>
  </xs:complexType>

  <!-- ═══════════════════════════════════════════════════════ UTIL TYPES -->
  <xs:complexType name="StringListType">
    <xs:sequence>
      <xs:element name="item" type="xs:string" maxOccurs="unbounded"/>
    </xs:sequence>
  </xs:complexType>

</xs:schema>
