Wikidata

Wikidata:Política de interfaz estable

This page is a translated version of the page Wikidata:Stable Interface Policy and the translation is 64% complete.
Outdated translations are marked like this.
Other languages:

Las interfaces públicas estables para el acceso a los datos son un componente crucial de cualquier repositorio de conocimiento público. Esta Política de Interfaz Estable define qué garantías ofrece y qué no ofrece el equipo de desarrollo de Wikidata en relación con la estabilidad de los formatos de datos y las APIs proporcionadas por Wikibase tal y como se despliegan en www.wikidata.org.

Definiciones

Esta sección define algunos términos cruciales utilizados en este documento.

  • Consumidor: software que lee e interpreta datos recibidos de Wikidata.
  • Cliente: software que hace llamadas a API públicas de Wikidata. Los clientes también suelen ser consumidores de datos.
  • Cliente/consumidor Conforme: Un cliente o consumidor que cumple con la especificación de los formatos y protocolos subyacentes que utiliza. Por ejemplo, un consumidor conforme que lee datos JSON cumple con la especificación JSON, y aceptará cualquier codificación permitida por la especificación JSON (RFC 7159). Un cliente que utiliza una API web cumplirá con la especificación HTTP, etc.
  • Cliente/consumidor con buen comportamiento: Un cliente o consumidor (conforme) que se implementa de forma robusta y compatible, teniendo en cuenta específicamente las garantías y limitaciones establecidas en este documento. Por ejemplo, un cliente que se comporte bien no se romperá al encontrar un nuevo tipo de datos.
  • Cambio de ruptura": un cambio en una API o en un formato de datos que viola las garantías dadas o ampliamente asumidas anteriormente. Los cambios de ruptura incluyen la eliminación de funciones, parámetros o campos de datos de la API y los cambios en la interpretación o el formato de los parámetros o los campos de datos.
  • Cambio significativo: un cambio en una API o en un formato de datos al que sería beneficioso que los clientes o consumidores se adaptaran, pero que no romperá a un cliente o consumidor con buen comportamiento. Los cambios significativos incluyen particularmente adiciones, como la introducción de nuevos tipos de datos o tipos de entidades, o la inclusión de información adicional en la salida de datos. Véase Extensibilidad más abajo.
  • Cambio insignificante: un cambio en una API o en un formato de datos que no se espera que tenga ningún impacto en un cliente que se comporte bien. Los cambios insignificantes incluyen cambios en los espacios en blanco fuera de los literales, así como el orden de los campos en un objeto JSON.
  • Interfaz estable: una API o formato de datos para la que se anunciarán los cambios significativos y de ruptura de acuerdo con la siguiente política. Las interfaces que se consideran estables se definen en 'Interfaces estables' más adelante en este documento.

Normativa de notificaciones

Esta sección define dónde y cuándo los operadores de clientes y los consumidores son notificados de cambios en una interfaz estable. No se garantiza nada en cuanto a interfaces inestables.

  • Los cambios de última hora en las interfaces estables se anunciarán con antelación en las listas de correo correspondientes (wikidata-tech, wikidata y pywikibot) y en el chat del proyecto. El anuncio se hará generalmente cuatro semanas antes, pero no menos de dos semanas antes de que el cambio se despliegue en https://www.wikidata.org/. El cambio estará disponible para su prueba al menos dos semanas antes de su despliegue en el sitio $test. Estos anuncios tendrán la palabra BREAKING en la línea de asunto.
  • Los cambios significativos en las interfaces estables se anunciarán en las listas de correo correspondientes (wikidata-tech, wikidata y pywikibot) y en el chat del proyecto. El anuncio se hará generalmente con al menos dos semanas de antelación, pero no menos de una semana después de que el cambio se haya desplegado en https://www.wikidata.org/. El cambio suele estar disponible para su prueba al menos dos semanas antes de su despliegue en $sitio de prueba.
  • Los cambios insignificantes en las interfaces estables generalmente no se anunciarán.
  • Los cambios en las "interfaces no estables" no pueden ser anunciados, incluso si son cambios de ruptura.
  • Los cambios significativos en esta política se anunciarán en las listas de correo pertinentes (wikidata-tech y wikidata) y en el chat del proyecto en el plazo de una semana desde que se realice el cambio.

Extensibilidad

Esta sección explica en qué manera nuestro modelo de datos y nuestros formatos de datos son extensibles. Los consumidores deberían tener en cuenta esta información para poder adaptar convenientemente cualquier estructura desconocida que se puedan encontrar en los datos.

El Wikibase Data Model está diseñado para ser extensible. En particular, es posible introducir nuevos tipos de datos y nuevos tipos de entidades. Los clientes y consumidores que se comportan bien deben estar preparados para encontrar tipos de datos y tipos de entidad desconocidos, y manejarlos con gracia, de una manera apropiada para el uso en cuestión. En muchos casos, es apropiado simplemente ignorar tales estructuras de tipo desconocido.

Del mismo modo, los bindings como la representación JSON del modelo de datos de Wikibase están diseñados para ser extensibles. Las estructuras de datos pueden añadirse en cualquier lugar sintácticamente apropiado siempre que no modifiquen el significado de los campos o estructuras de datos preexistentes, y siempre que su adición no rompa ninguna garantía respecto a las estructuras de datos que las contienen. Esto sigue la idea del principio de sustitución de Liskov: lo que estaba garantizado sobre una estructura de datos antes de la adición debe seguir estando garantizado después de la adición.

Si no se dan garantías explícitas sobre la estructura y el contenido de una estructura de datos, los siguientes principios deberían orientar sobre si un cambio debe considerarse un cambio de ruptura:

En las estructuras basadas en listas (aka. arrays) y mapas (aka. hashes u otros objetos), como es JSON, añadir una clave a un mapa no se considera un cambio de ruptura, siempre que el nuevo campo no cambie la interpretación de ningún otro campo en la estructura (ni en ninguna estructura circundante). Sin embargo, añadir una estructura a una lista o un conjunto se considera un cambio de ruptura si rompe las suposiciones sobre el tipo de estructura que cabe esperar en la lista, o bajo qué condiciones se incluiría una estructura en la lista.

Por conveniencia, las listas se consideran homogéneas y solo deben contener un tipo de elemento, a menos que se especifique lo contrario. Por lo tanto, añadir una estructura de datos a una lista es un cambio de ruptura si esa estructura de datos no es compatible con el tipo de estructura que la lista estaba previamente definida o implicada para contener.

En una representación de datos tabulares, como un esquema de base de datos relacional, la adición de campos no se considera un cambio de ruptura. Cualquier cambio en la interpretación de un campo, así como la eliminación de campos, se considera de ruptura. Los cambios en los índices únicos o claves primarias existentes son cambios de ruptura; los cambios en otros índices, así como la adición de nuevos índices, no son cambios de ruptura.

En las estructuras tipo DOM basadas en elementos anidados con atributos, como es el XML, añadir un atributo no se considera un cambio de ruptura, siempre que el nuevo atributo no cambie la interpretación de ningún otro campo de la estructura (ni de ninguna estructura circundante). Añadir un nuevo tipo de elemento a un elemento padre tampoco se considera una ruptura, si ese elemento padre es heterogéneo y actúa esencialmente como un mapa. Sin embargo, si el elemento padre se define o implica que es una lista homogénea de un tipo específico de elemento hijo, añadir otro tipo de elemento se considera un cambio de ruptura.

En el caso de los formatos de datos que permiten el espaciado de nombres, como hace XML, los consumidores pueden ignorar los nombres (nombres de atributos, nombres de elementos) que pertenezcan a un espacio de nombres no mencionado explícitamente por la especificación del formato de datos. Las adiciones y modificaciones de estructuras de datos de otros espacios de nombres no se consideran cambios de ruptura.

Por el contrario, las siguientes modificaciones son ejemplos de cambios de ruptura y, por tanto, no pueden utilizarse para ampliar un formato: la eliminación de campos, los cambios en el tipo o el formato de un valor primitivo, los cambios en la interpretación o la función de un campo de datos, así como los cambios en el tipo de elemento de una colección, como se ha descrito anteriormente.

Stable Data Formats

This section lists the data formats we consider stable. These data formats are subject to the above notification policy.

The RDF mapping of the Wikibase Data Model, as used in RDF dumps as well as in the Linked Data Interface and the Query Service, is considered a stable data format. The Wikibase vocabulary is formally defined by http://wikiba.se/ontology. Any changes to the structure or interpretation of the mapping are subject to the above notification policy. As per the general principles of RDF, additional information introduced at any time, in any location, about any subject, is not considered a breaking change.

The JSON binding of the Wikibase Data Model as used in JSON dumps, with the web API, and with the Linked Data Interface, is considered a stable data format. Any changes to the structure or interpretation of the mapping are subject to the above notification policy. Following the flexible nature of JSON, the addition of fields to JSON objects is not considered a breaking change. Well-behaved consumers should be prepared to ignore such additional fields.

Stable Public APIs

This section lists the interfaces we consider stable. These interfaces are subject to the above notification policy.

The Wikibase Web API accessible via https://www.wikidata.org/w/api.php is considered a stable interface. Changes to the parameters, operation, or returned data structure are subject to the above notification policy.

The Linked Data Interface accessible via https://www.wikidata.org/wiki/Special:EntityData and https://www.wikidata.org/entity/... is considered a stable interface. Changes to the parameters, operation, or returned data structure are subject to the above notification policy.

The Wikidata Query Service accessible via https://query.wikidata.org/ is considered a stable interface. It provides a full SPARQL endpoint. Changes to the parameters, operation, or returned data structure are subject to the above notification policy.

La biblioteca Lua para Wikibase para wikis clientes está considerada una interfaz estable. Los cambios en las funciones, parámetros o estructuras de datos devueltos disponibles están sujetos a la mencionada política de notificaciones.

Para permitir una mejor integración de accesorios, los hooks en JavaScript documentados en el archivo hooks-js.txt distribuido junto con el código fuente de Wikibase se consideran estables.

We acknowledge that third party tools on Cloud VPS and Toolforge may rely on the Wikibase database schema. Because of this, changes to the available tables and fields are subject to the above notification policy. However, note that the database schema is not designed to be a public API, and less consideration is given to backwards compatibility.

Interfaces inestables

Esta sección enumera algunas interfaces que actualmente no consideramos que sean estables, y por tanto pueden cambiar de forma que causen incompatibilidades sin avisar.

Los volcados XML de MediaWiki no están considerados una interfaz estable. Los volcados XML de MediaWiki contienen los datos crudos de las revisiones de páginas en su representación interna. La representación interna de entidades de Wikibase no es una interfaz estable. Ha cambiado significativamente en el pasado, y puede volver a hacerlo en el futuro. Pueden coexistir varias representaciones distintas de contenido de Wikibase en un mismo volcado XML.

Raw revision content as returned by the MediaWiki core API is not considered a stable interface, as it uses the internal representation of the content, just like the XML dumps. Raw revision content is returned from API queries such as api.php?action=query&prop=revisions&titles=Q42&rvprop=timestamp|user|comment|content.

Wikibase PHP code is not considered a stable interface. Although the Wikibase project now provides official releases, wikidata.org still receives rolling deployment of Wikibase code. Therefore there is no point in time at which any given PHP class or interface can be assumed to remain stable.

Wikibase JavaScript code is not considered a stable interface. Although the Wikibase project now provides official releases, wikidata.org still receives rolling deployment of Wikibase code. Therefore there is no point in time at which JavaScript code can be assumed to remain stable. This means that Gadgets cannot rely on the JavaScript code to remain stable.

The HTML DOM structure generated by Wikibase is not considered a stable interface. This means that Gadgets cannot rely on the DOM structure to remain stable.

Outlook

This section provides information about improvements that are planned or considered for the future.

The JSON binding should be versioned (using the semantic versioning convention), so consumers know what structures to expect, and how to interpret them. See phab:T92961.

Wikibase JavaScript code should indicate stable interfaces that can be confidently used by Gadgets.

Wikibase should provide some basic guarantees about the HTML DOM structure it generates, so Gadgets can confidently interact with the DOM.

For 3rd party installations, Wikibase now has regular releases linked to MediaWiki releases. However, Wikidata will continue to use rolling deployments of the latest development version.

Historia

Esta sección lista pasada y planificó romper cambios. La lista de cambios pasados antes de la implementación de esta política puede ser incompleta. Cada cambio tendría que ser listado con la fecha de anuncio y la fecha de despliegue, idealmente acompañado con un enlace al anuncio y #cualquier @ticket #pertinente.

Wikidata Policies and Guidelines
Policies
Guidelines
Editing items
Policies about specific topics/fields
Retrieved from "https://www.wikidata.org/w/index.php?title=Wikidata:Stable_Interface_Policy/es&oldid=1843444462"