Merge pull request #6 from datosgobar/new-validate-catalog-response-f…

…ormat-#3

closes #3

HISTORY.md

@@ -1,12 +1,21 @@
 History
 ===
 
-0.0.13 (2016-11-25)
+0.1.0 (2016-11-30)
 ------------------
 
+Primera versión para uso productivo del paquete.
+
+* La instalación via `pip install` debería reconocer correctamente la ubicación de los validadores por default.
+* El manejo de data.json's ubicados remotamente se hace en función del resultado de `urlparse.urlparse`
+* El formato de respuesta de `validate_catalog` se adecúa a la última especificación (ver [`samples/validate_catalog_returns.json`](samples/validate_catalog_returns.json).
+
+0.0.13 (2016-11-25)
+-------------------
+
 * Intentar que la instalación del paquete sepa donde están instalados los schemas por default
 
 0.0.12 (2016-11-25)
-------------------
+-------------------
 
 * Primera versión propuesta para v0.1.0

README.md

@@ -14,8 +14,6 @@ Paquete en python con herramientas para manipular y validar metadatos de catálo
 
 ## Instalación
 
-Instalar la librería debería ser tan sencillo como un `pip install`:
-
 * **Producción:** Desde cualquier parte
 
 ```bash
@@ -29,15 +27,45 @@ $ pip install -e .
 
 ## Uso
 
-La librería implementa un objeto, `DataJson`, con varios métodos para verificar la integridad de los archivos `data.json` y manipular su contenido. De particular interés son `is_valid_catalog` y `validate_catalog`.
+La librería implementa el objeto `DataJson` con varios métodos para verificar la integridad de archivos de metadatos `data.json` (locales o remotos) y manipular su contenido.
 
-### Validar la estructura de un data.json contra el esquema por default que incluye la librería
+### Setup
 
-#### Archivo data.json local
+`DataJson` utiliza un esquema default que cumple con el perfil de metadatos recomendado en la [Guía para el uso y la publicación de metadatos (v0.1)](https://github.com/datosgobar/paquete-apertura-datos/raw/master/docs/Gu%C3%ADa%20para%20el%20uso%20y%20la%20publicaci%C3%B3n%20de%20metadatos%20(v0.1).pdf) del [Paquete de Apertura de Datos](https://github.com/datosgobar/paquete-apertura-datos).
+
+```python
+from pydatajson import DataJson
+
+dj = DataJson()
+```
+
+Si se desea utilizar un esquema alternativo, se debe especificar un **directorio absoluto** donde se almacenan los esquemas (`schema_dir`) y un nombre de esquema de validación (`schema_filename`), relativo al directorio  de los esquemas. Por ejemplo, si nuestro esquema alternativo se encuentra en `/home/datosgobar/metadatos-portal/esquema_de_validacion.json`, especificaremos:
+
+```python
+from pydatajson import DataJson
+
+dj = DataJson(schema_filename="esquema_de_validacion.json",
+              schema_dir="/home/datosgobar/metadatos-portal")
+```
+
+### Posibles validaciones de catálogos
+
+- Si se desea un **resultado sencillo (V o F)** sobre la validez de la estructura del catálogo, se utilizará **`is_valid_catalog(datajson_path_or_url)`**.
+- Si se desea un **mensaje de error detallado**, se utilizará **`validate_catalog(datajson_path_or_url)`**.
+
+### Ubicación del catálogo a validar
+
+Ambos métodos mencionados de `DataJson()` son capaces de validar archivos `data.json` locales o remotos:
+
+- Para validar un **archivo local**, `datajson_path_or_url` deberá ser el **path absoluto** a él.
+- Para validar un **archivo remoto**, `datajson_path_or_url` deberá ser una **URL que comience con 'http' o 'https'**.
 
-DataJson es capaz de validar archivos locales en cualquier directorio (accesible) siempre y cuando se provea el path absoluto a él.
 Por conveniencia, la carpeta [`tests/samples/`](tests/samples/) contiene varios ejemplos de `data.json`s bien y mal formados con distintos tipos de errores.
 
+### Ejemplos
+
+#### Archivo data.json local
+
 ```python
 from pydatajson import DataJson
 
@@ -50,19 +78,26 @@ print validation_result
 True
 
 print validation_report
-{ 
-    "status": "OK", 
-    "error": { 
-        "catalog": [], 
-        "dataset": [] 
-    }   
-}   
+{
+    "status": "OK",
+    "error": {
+        "catalog": {
+            "status": "OK",
+            "title": "Datos Argentina"
+        },
+        "dataset": [
+            {
+                "status": "OK",
+                "title": "Sistema de contrataciones electrónicas"
+            }
+
+        ]
+    }
+}
 ```
 
 #### Archivo data.json remoto
 
-También es posible proveer una URL remota al archivo `data.json` de un portal productivo. Internamente, DataJson entiende que si el path del archivo a validar comienza con "http", se trata de una URL remota.
-
 ```python
 datajson_url = "http://104.131.35.253/data.json"
 validation_result = dj.is_valid_catalog(datajson_url)
@@ -75,21 +110,40 @@ print validation_report
 {
     "status": "ERROR",
     "error": {
-        "catalog": ["Título del portal"],
-        "dataset": ["Dataset ejemplo 04", "Dataset ejemplo 03",
-                    "Dataset ejemplo 02", "Dataset ejemplo 01"]
-    }   
-}   
+        "catalog": {
+            "status": "ERROR",
+            "title": "Título del portal"
+        },
+        "dataset": [
+            {
+                "status": "ERROR",
+                "title": "Dataset ejemplo 04"
+            },
+            {
+                "status": "ERROR",
+                "title": "Dataset ejemplo 03"
+            },
+            {
+                "status": "ERROR",
+                "title": "Dataset ejemplo 02"
+            },
+            {
+                "status": "ERROR",
+                "title": "Dataset ejemplo 01"
+            }
+        ]
+    }
+}
 ```
 
 ## Tests
 
-Los tests de la librería se desarrollaron con `nose`. Para correrlos, desde la raíz del repositorio:
+Los tests se corren con `nose`. Desde la raíz del repositorio:
 ```
-$ pip install nose # Sólo la primera vez
+$ pip install nose  # Sólo la primera vez
 $ nosetests
 ```
 
 ## Créditos
 
-El validador de archivos `data.json` desarrollado no es más que un conveniente envoltorio alrededor de la librería [`jsonschema`](https://github.com/Julian/jsonschema), que implementa el estándar definido por [JSONSchema.org](http://json-schema.org/).
+El validador de archivos `data.json` desarrollado es mayormente un envoltorio (*wrapper*) alrededor de la librería [`jsonschema`](https://github.com/Julian/jsonschema), que implementa el vocabulario definido por [JSONSchema.org](http://json-schema.org/) para anotar y validar archivos JSON.

docs/HISTORY.md

@@ -1,7 +1,20 @@
 History
 ===
 
-0.0.12 (2016-11-25)
+0.1.0 (2016-11-30)
 ------------------
 
+Primera versión para uso productivo del paquete.
+* La instalación via `pip install` debería reconocer correctamente la ubicación de los validadores por default.
+* El manejo de data.json's ubicados remotamente se hace en función del resultado de `urlparse.urlparse`
+* El formato de respuesta de `validate_catalog` se adecúa a la última especificación (ver [`samples/validate_catalog_returns.json`](samples/validate_catalog_returns.json).
+
+0.0.13 (2016-11-25)
+-------------------
+
+* Intentar que la instalación del paquete sepa donde están instalados los schemas por default
+
+0.0.12 (2016-11-25)
+-------------------
+
 * Primera versión propuesta para v0.1.0

docs/README.md

@@ -29,15 +29,32 @@ $ pip install -e .
 
 ## Uso
 
-La librería implementa un objeto, `DataJson`, con varios métodos para verificar la integridad de los archivos `data.json` y manipular su contenido. De particular interés son `is_valid_catalog` y `validate_catalog`.
+### Setup
+La librería implementa un objeto, `DataJson`, con varios métodos para verificar la integridad de archivos `data.json` (locales o remotos) y manipular su contenido. Si se desea, se puede especificar un directorio absoluto (`schema_dir`) y un nombre de esquema de validacion (`schema_filename`) particular, pero *casi siempre*, sus valores por default serán adecuados, así que para empezar a trabajar, alcanza con:
+```python
+from pydatajson import DataJson
+
+dj = DataJson()
+```
 
-### Validar la estructura de un data.json contra el esquema por default que incluye la librería
+### Posibles validaciones de catálogos
 
-#### Archivo data.json local
+- Si se desea un **resultado sencillo (V o F)** sobre la validez de la estructura del catálogo, se utilizará **`is_valid_catalog(datajson_path_or_url)`**.
+- Si se desea un **mensaje de error detallado**, se utilizará **`validate_catalog(datajson_path_or_url)`**.
+
+### Ubicación del catálogo a validar
+
+Ambos métodos mencionados de `DataJson()` son capaces de validar archivos `data.json` locales o remotos:
+- para validar un **archivo local**, `datajson_path_or_url` deberá ser el **path absoluto** a él.
+- para validar un archivo remoto, `datajson_path_or_url` deberá ser una **URL que comience con 'http' o 'https'**.
 
-DataJson es capaz de validar archivos locales en cualquier directorio (accesible) siempre y cuando se provea el path absoluto a él.
 Por conveniencia, la carpeta [`tests/samples/`](tests/samples/) contiene varios ejemplos de `data.json`s bien y mal formados con distintos tipos de errores.
 
+
+### Ejemplos
+
+#### Archivo data.json local
+
 ```python
 from pydatajson import DataJson
 
@@ -50,19 +67,26 @@ print validation_result
 True
 
 print validation_report
-{ 
-    "status": "OK", 
-    "error": { 
-        "catalog": [], 
-        "dataset": [] 
-    }   
-}   
+{
+    "status": "OK",
+    "error": {
+        "catalog": {
+            "status": "OK",
+            "title": "Datos Argentina"
+        },
+        "dataset": [
+            {
+                "status": "OK",
+                "title": "Sistema de contrataciones electrónicas"
+            }
+
+        ]
+    }
+}
 ```
 
 #### Archivo data.json remoto
 
-También es posible proveer una URL remota al archivo `data.json` de un portal productivo. Internamente, DataJson entiende que si el path del archivo a validar comienza con "http", se trata de una URL remota.
-
 ```python
 datajson_url = "http://104.131.35.253/data.json"
 validation_result = dj.is_valid_catalog(datajson_url)
@@ -75,11 +99,30 @@ print validation_report
 {
     "status": "ERROR",
     "error": {
-        "catalog": ["Título del portal"],
-        "dataset": ["Dataset ejemplo 04", "Dataset ejemplo 03",
-                    "Dataset ejemplo 02", "Dataset ejemplo 01"]
-    }   
-}   
+        "catalog": {
+            "status": "ERROR",
+            "title": "Título del portal"
+        },
+        "dataset": [
+            {
+                "status": "ERROR",
+                "title": "Dataset ejemplo 04"
+            },
+            {
+                "status": "ERROR",
+                "title": "Dataset ejemplo 03"
+            },
+            {
+                "status": "ERROR",
+                "title": "Dataset ejemplo 02"
+            },
+            {
+                "status": "ERROR",
+                "title": "Dataset ejemplo 01"
+            }
+        ]
+    }
+}
 ```
 
 ## Tests
@@ -92,4 +135,4 @@ $ nosetests
 
 ## Créditos
 
-El validador de archivos `data.json` desarrollado no es más que un conveniente envoltorio alrededor de la librería [`jsonschema`](https://github.com/Julian/jsonschema), que implementa el estándar definido por [JSONSchema.org](http://json-schema.org/).
+El validador de archivos `data.json` desarrollado es mayormente un envoltorio (*wrapper*) alrededor de la librería [`jsonschema`](https://github.com/Julian/jsonschema), que implementa el vocabulario definido por [JSONSchema.org](http://json-schema.org/) para anotar y validar archivos JSON.

pydatajson/__init__.py

@@ -6,4 +6,4 @@
 
 __author__ = """Datos Argentina"""
 __email__ = 'datos@modernizacion.gob.ar'
-__version__ = '0.0.12'
+__version__ = '0.1.0'