Conceptes

Estructura del resultat

El resultat respon tres preguntes: quins valors s’han calculat, quins problemes s’han trobat i quina substitució o canvi es pot proposar per a cada aparició.

Una mètrica activa sempre s’avalua, però la sortida depèn del tipus: les mesures apareixen una vegada; les regles només apareixen quan troben ocurrències.

result.measurements[]

Mesures

Valors numèrics calculats. Cada entrada de result.measurements s'identifica per metric_id; value s'interpreta juntament amb unit i implementation_version.

Mètriques i regles →

result.recommendations[]

Recomanacions

Problemes agrupats per regla. Cada element explica el problema i reuneix a occurrences totes les aparicions concretes al text.

Mètriques i regles →

Estructura d’una recomanació i els seus canvis

Una recommendation descriu el tipus de problema; cada occurrence indica on apareix i si arText disposa d’una substitució o edició concreta.

recommendations[].metric_idIdentificador estable de la regla. La seva definició es consulta a GET /v1/metrics.

recommendations[].summaryExplicació del problema trobat en aquest informe.

recommendations[].guidance[]Orientació general per revisar el problema; no equival necessàriament a una substitució literal.

recommendations[].examplesExemples redactats que il·lustren la recomanació, en text pla amb salts de línia significatius. Acompanyen la regla, no citen el text analitzat i no varien d'un informe a un altre. null quan la regla no té exemples.

occurrences[].textFragment detectat per la mètrica.

occurrences[].start / endRang sobre el text original mesurat en punts de codi Unicode; start és inclusiu i end exclusiu.

occurrences[].replacementSubstitució textual preferida quan existeix. null significa que la regla no ofereix una substitució directa.

occurrences[].alternatives[]Altres substitucions revisades, sense repetir replacement. Pot ser un array buit.

occurrences[].edits[]Canvis segurs normalitzats com {start, end, text}. text buit elimina el rang i start igual a end insereix text.

Una ocurrència continua sent un problema vàlid encara que replacement sigui null i edits estigui buit. En aquest cas cal mostrar l’explicació i deixar la revisió a la persona usuària; la integració no ha de fabricar cap canvi.

Offsets: com retallar el fragment

start i end es refereixen al text EXACTE que vas enviar a text: sense normalitzar, sense retallar espais i sense reordenar. L'informe no et torna aquest text, així que la unitat importa.

offset_unit és unicode_code_points, no unitats UTF-16 ni bytes. Un sol caràcter fora del BMP —un emoji, certs ideogrames, alguns símbols matemàtics— desplaça tots els offsets posteriors en els llenguatges que indexen en UTF-16. És una fallada que no apareix a les proves i sí amb documents reals.

Pythontexto[start:end] — correcte tal com és: les cadenes de Python ja són punts de codi.

JavaScript[...texto].slice(start, end).join("") — text.slice(start, end) NO és correcte. L'SDK oficial porta sliceByCodePoints i codePointToUtf16Index.

Java · C#texto.codePoints() / StringInfo — les cadenes són UTF-16; cal convertir abans d'indexar.

Go[]rune(texto)[start:end] — les cadenes són bytes; converteix-les a runes.

Guarda tu el text analitzat, indexat per report_id o pel teu external_id: és l'únic lloc on els offsets signifiquen alguna cosa, i l'API no el conserva més enllà de la retenció de l'informe.

200 · Completat

{
  "error": null,
  "external_id": "document-123",
  "position_in_queue": null,
  "report_id": "rep_7f12a4c8",
  "result": {
    "genre": {
      "domain": {
        "name": "Llenguatge clar",
        "slug": "llenguatge-clar"
      },
      "text_type": {
        "name": "Text juridicoadministratiu",
        "slug": "text-juridic-administratiu-dirigit-a-la-ciutadania"
      }
    },
    "language": "ca",
    "measurements": [
      {
        "implementation_version": "1.0",
        "metric_id": "word-count",
        "unit": "words",
        "value": 12
      }
    ],
    "offset_unit": "unicode_code_points",
    "recommendations": [
      {
        "category": "lexical",
        "explanation": null,
        "guidance": [
          "Elimina l\u2019expressi\u00f3 si el context ho permet."
        ],
        "id": "rec_1",
        "implementation_version": "1.0",
        "metric_id": "redundant-expressions",
        "metric_title": "Eliminaci\u00f3 d\u2019expressions redundants",
        "occurrences": [
          {
            "alternatives": [],
            "edits": [
              {
                "end": 16,
                "start": 0,
                "text": ""
              }
            ],
            "end": 16,
            "id": "occ_1",
            "paragraph_index": 0,
            "replacement": null,
            "sentence_index": 0,
            "start": 0,
            "text": "En el dia d\u2019avui"
          }
        ],
        "summary": "Conv\u00e9 formular el fragment d\u2019una manera m\u00e9s directa."
      }
    ],
    "schema_version": "2.0"
  },
  "status": "completed"
}

SegüentMètriques i regles