simplenote-web/data-format.md

SimpleNote - Formato de Datos

1. Archivos JSON de Metadata

Todos los archivos de metadata son JSON planos, almacenados junto a su contenido en el filesystem.

---

2. .library.json

Define una librería (equivalente a una carpeta/directorio).

Ubicación: data/libraries/{library-uuid}/.library.json

Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "name", "path", "createdAt", "updatedAt"],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "description": "UUID único de la librería"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "description": "Nombre visible de la librería"
    },
    "parentId": {
      "type": ["string", "null"],
      "format": "uuid",
      "description": "ID del padre directo. Null para root."
    },
    "path": {
      "type": "string",
      "description": "Ruta relativa desde DATA_ROOT (ej: libraries/uuid)"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp de creación ISO8601"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Timestamp de última modificación ISO8601"
    }
  }
}

Ejemplo:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Backend Requirements",
  "parentId": null,
  "path": "libraries/550e8400",
  "createdAt": "2026-03-28T09:00:00Z",
  "updatedAt": "2026-03-28T09:00:00Z"
}

Ejemplo anidado:

{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "API Specs",
  "parentId": "550e8400-e29b-41d4-a716-446655440000",
  "path": "libraries/550e8400/sub-libraries/660e8400",
  "createdAt": "2026-03-28T10:00:00Z",
  "updatedAt": "2026-03-28T10:00:00Z"
}

---

3. .meta.json

Metadata de un documento individual.

Ubicación: data/libraries/{lib-uuid}/documents/{doc-uuid}/.meta.json

Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["id", "title", "tags", "type", "libraryId", "createdAt", "updatedAt"],
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid"
    },
    "title": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "tags": {
      "type": "array",
      "items": { "type": "string" },
      "uniqueItems": true
    },
    "type": {
      "type": "string",
      "enum": ["requirement", "note", "spec", "general"]
    },
    "status": {
      "type": "string",
      "enum": ["draft", "approved", "implemented"]
    },
    "priority": {
      "type": "string",
      "enum": ["high", "medium", "low"]
    },
    "libraryId": {
      "type": "string",
      "format": "uuid"
    },
    "createdBy": {
      "type": "string",
      "description": "Agent ID o user ID que creó el documento"
    },
    "createdAt": {
      "type": "string",
      "format": "date-time"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time"
    }
  }
}

Ejemplo:

{
  "id": "770e8400-e29b-41d4-a716-446655440002",
  "title": "API Authentication Design",
  "tags": ["backend", "api", "auth"],
  "type": "requirement",
  "status": "draft",
  "priority": "high",
  "libraryId": "550e8400-e29b-41d4-a716-446655440000",
  "createdBy": "agent-001",
  "createdAt": "2026-03-28T10:00:00Z",
  "updatedAt": "2026-03-28T10:00:00Z"
}

---

4. .tag-index.json

Índice global de tags. Rebuild completo o incremental.

Ubicación: data/.tag-index.json

Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["version", "updatedAt", "tags"],
  "properties": {
    "version": {
      "type": "integer",
      "const": 1,
      "description": "Versión del formato de índice"
    },
    "updatedAt": {
      "type": "string",
      "format": "date-time",
      "description": "Última rebuild del índice"
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type": "array",
        "items": { "type": "string", "format": "uuid" },
        "uniqueItems": true
      },
      "description": "Map tag → array de document IDs"
    }
  }
}

Ejemplo:

{
  "version": 1,
  "updatedAt": "2026-03-28T12:00:00Z",
  "tags": {
    "backend": [
      "770e8400-e29b-41d4-a716-446655440002",
      "880e8400-e29b-41d4-a716-446655440003"
    ],
    "api": [
      "770e8400-e29b-41d4-a716-446655440002"
    ],
    "auth": [
      "770e8400-e29b-41d4-a716-446655440002",
      "990e8400-e29b-41d4-a716-446655440004"
    ]
  }
}

---

5. .auth-tokens.json

Tokens de API válidos.

Ubicación: data/.auth-tokens.json

Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "type": "object",
  "required": ["version", "tokens"],
  "properties": {
    "version": {
      "type": "integer",
      "const": 1
    },
    "tokens": {
      "type": "array",
      "items": {
        "type": "object",
        "required": ["token", "label", "createdAt"],
        "properties": {
          "token": {
            "type": "string",
            "pattern": "^snk_"
          },
          "label": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}

Ejemplo:

{
  "version": 1,
  "tokens": [
    {
      "token": "snk_a1b2c3d4e5f6g7h8i9j0",
      "label": "cli-default",
      "createdAt": "2026-03-28T00:00:00Z"
    },
    {
      "token": "snk_k9j8i7h6g5f4e3d2c1b",
      "label": "hiro-workstation",
      "createdAt": "2026-03-28T01:00:00Z"
    }
  ]
}

---

6. Documento Markdown (index.md)

Archivo de contenido con frontmatter YAML.

6.1 Frontmatter

---
id: REQ-001
title: Título del Requerimiento
type: requirement        # requirement | note | spec | general
priority: high          # high | medium | low
status: draft           # draft | approved | implemented
tags: [backend, api]
createdBy: agent-001
createdAt: 2026-03-28
---

6.2 Body

Markdown standard con headers, listas, código, etc.

6.3 Ejemplo Completo

---
id: REQ-001
title: API Authentication Design
type: requirement
priority: high
status: draft
tags: [backend, api, auth]
createdBy: agent-001
createdAt: 2026-03-28
---

# API Authentication Design

## Descripción
El sistema debe soportar autenticación via tokens Bearer para todas las rutas
protegidas bajo `/api/v1/*` excepto `/api/v1/auth/token`.

## Criterios de Aceptación
- [ ] Endpoint POST /api/v1/auth/token acepta credenciales y retorna token
- [ ] Middleware extrae token del header `Authorization: Bearer <token>`
- [ ] Middleware retorna 401 si header ausente o token inválido
- [ ] Token tiene prefijo `snk_` para identificación fácil

## Notas
Tokens en esta versión son secretos compartidos. Para producción se recomienda
OAuth2 o JWT firmados.

---

7. Tabla Resumen de Archivos

Archivo	Ubicación	Propósito
.library.json	libraries/{id}/	Metadata de librería
.meta.json	libraries/{lib}/documents/{id}/	Metadata de documento
index.md	libraries/{lib}/documents/{id}/	Contenido del documento
.tag-index.json	DATA_ROOT/	Índice global tag → docs
.auth-tokens.json	DATA_ROOT/	Tokens API válidos
config.json	~/.config/simplenote/	Config local del CLI