La inclusión, según se define en este documento, es un tipo específico de transformación de conjuntos de información (véase [XML Information Set]).
4.1 Ubicación de inclusión
El valor del atributo href, una vez aplicados los mecanismos de escape según lo indicado en 4.1.1 Mecanismos de escape para los valores de los atributos, se interpreta ya sea como una referencia URI o como una referencia IRI. EL URI base para los URI o IRI relativos es el URI base del elemento xi:include según se especifica en [XML Base]. [Definición: El URI o IRI resultante de la resolución del valor normalizado del atributo href (o la cadena vacía si no existe tal atributo) a la forma de URI o IRI absoluto se denomina ubicación de inclusión.]
La inexistencia de un valor para el atributo href, sea por la presencia de href="" o por la ausencia del atributo href, representa un caso que puede ser incompatible con ciertas estrategias de implementación. Por ejemplo, puede ocurrir que un procesador XInclude no tenga una representación textual del conjunto de información de origen para incluir como parse="text"; o que cuestiones relacionadas con la transmisión en flujo continuo le impidan acceder a otra parte del documento usando parse="xml" y un XPointer. Una implementación puede optar por tratar la inexistencia de valor para el atributo href como un error de recurso. Las implementaciones deberían documentar las condiciones en las que ocurren tales errores de recurso.
4.1.1 Mecanismos de escape para los valores del atributo href
El valor del atributo href se convierte a una referencia URI o una referencia IRI, según sea adecuado para la implementación.
Actualmente se está trabajando en producir un RFC donde se definirán los Identificadores de Recurso Internacionalizados (IRI). Puesto que este trabajo aún no está terminado, en esta sección definimos las referencias IRI sintácticamente. Esperamos emitir una errata que reemplace partes de esta sección con una referencia al RFC cuando éste sea publicado. Para una definición y una discusión de los IRI en términos más generales, véase [IRI draft] (trabajo en progreso).
[Definición: Una referencia IRI es una cadena que puede convertirse en una referencia URI aplicando los mecanismos de escape a los siguientes caracteres:]
-
los caracteres del plano Unicode 0: #xA0 - #xD7FF, #xF900-#xFDCF, #xFDF0-#xFFEF
-
los caracteres de los planos Unicode 1-14: #x10000-#x1FFFD ... #xE0000-#xEFFFD
Para convertir el valor del atributo href a una referencia IRI, se deben aplicar mecanismos de escape a los siguientes caracteres:
-
espacio #x20
Observación:
Se recomienda a los autores evitar el uso de espacios a los que no se hayan aplicado mecanismos de escape, ya que XML Schema los ha identificado como un riesgo para la interoperabilidad.
-
los delimitadores < #x3C, > #x3E y " #x22
-
los caracteres desaconsejados { #x7B, } #x7D, | #x7C, \ #x5C, ^ #x5E y ` #x60
El mecanismo de escape para estos caracteres es el siguiente:
-
Cada carácter adicional se convierte a uno o más bytes en UTF-8 [Unicode].
-
A los bytes resultantes se les aplica el mecanismo de escape de los URI (es decir, se los convierte a %HH, donde HH es la representación hexadecimal del valor del byte).
-
Se reemplaza el carácter original por la secuencia de caracteres resultante.
Para convertir una referencia IRI a referencia URI, se debe aplicar el mismo mecanismo de escape a los caracteres adicionales permitidos en un IRI.
4.1.2 Uso de XInclude con negociación de contenido
El uso de un mecanismo como la negociación de contenido del HTTP [IETF RFC 2616] añade al uso de XInclude otro nivel de posible complejidad. Los desarrolladores que usen XInclude en situaciones donde es probable o posible que haya negociación de contenido, deberían ser conscientes de la posibilidad de que el contenido que incluyan difiera estructuralmente de lo que esperaban, incluso aunque sea contenido XML. Por ejemplo, un único URI o IRI puede devolver una representación del recurso en XML puro, una representación XSL-FO [XSL-FO] o una representación XHTML [XHTML], así como versiones en diferentes codificaciones de caracteres o diferentes lenguajes.
Los autores cuyo procesamiento XInclude dependa de la recepción de un vocabulario de XML en particular, deberían usar los atributos accept y accept-language para aumentar la probabilidad de recibir el recurso en el formato esperado.
4.2 Ítems incluidos cuando parse="xml"
Cuando parse="xml", luego de resolver la referencia de la ubicación de inclusión se recupera el recurso y se crea un conjunto de información analizando el recurso como si el tipo de medio fuera application/xml (incluida la determinación de la codificación de caracteres).
Observación:
Los detalles de la creación de un conjunto de información se dejan deliberadamente sin especificar, para permitir flexibilidad a las implementaciones y evitar la definición de un modelo de procesamiento particular para los componentes de la arquitectura XML. Por ejemplo, esta especificación no impone reglas sobre detalles particulares, como si se usan esquemas XML o validación DTD.
Observación:
La codificación de caracteres del recurso que hace la inclusión puede ser diferente de la del recurso incluido. Esto no afecta al conjunto de información resultante, pero quizá deba ser tenido en cuenta en una serialización posterior.
Si por cualquier motivo un recurso no está disponible (por ejemplo, porque el recurso no existe, hay dificultades de conexión o restricciones de seguridad que impiden su recuperación, el esquema URI no es de un tipo que admita recuperación, la codificación del recurso es incompatible o mecanismos propios de la implementación determinan que el recurso no es XML), el resultado es un error de recurso. Si el contenido del recurso no es XML bien formado, el resultado es un error fatal.
Observación:
La distinción entre error de recurso y error fatal depende en cierta medida de la implementación. Supóngase una ubicación de inclusión que devuelve un documento HTML, tal vez una página de error. Un procesador podría determinar que el recurso no permite crear un conjunto de información (por ejemplo, examinando el tipo de medio) y generar un error de recurso, con lo que se habilita el mecanismo de recuperación de error. Otro procesador no provisto de esa heurística podría intentar analizar el recurso como si fuera XML y encontrarse con un error (fatal) debido a que el recurso no está bien formado.
[Definición: Los elementos xi:include en este conjunto de información se procesan recursivamente para crear el conjunto de información adquirido. Tratándose de referencias dentro del mismo documento (mediante el atributo xpointer) se usa como conjunto de información adquirido el conjunto de información de origen.]
[Definición: La porción del conjunto de información adquirido que se incluirá se denomina objetivo de inclusión.] El ítem de información de documento del conjunto de información adquirido hace las veces de objetivo de inclusión a menos que el atributo xpointer esté presente e identifique un subrecurso. Los procesadores XInclude deben ser compatibles con XPointers de las formas descritas en [XPointer Framework] y [XPointer element() scheme]. Los procesadores XInclude opcionalmente pueden admitir otras formas de XPointer como las descritas en [XPointer xpointer() Scheme]. Un error en el XPointer es un error de recurso.
El esquema xpointer() ([XPointer xpointer() Scheme]) no se especifica en términos de [XML Information Set], sino que se basa en el modelo de datos [XPath 1.0], porque el conjunto de información XML aún no había sido desarrollado. La conversión de ubicaciones de nodo XPath a ítems de información es muy sencilla. Sin embargo, xpointer() da por sentado que se han expandido todas las entidades. Por eso, intentar resolver un esquema xpointer() en un documento que contiene ítems de información de referencia de entidad no expandida es un error fatal.
El conjunto de ítems incluidos de nivel superior se deriva del conjunto de información adquirido de la manera que se explica a continuación.
4.2.1 Ítems de información de documento
El objetivo de inclusión puede ser un ítem de información de documento (por ejemplo, si no se indicó un atributo xpointer o si el XPointer hace referencia explícitamente a la raíz del documento). En este caso, el conjunto de ítems incluidos de nivel superior está formado por los hijos del ítem de información de documento del conjunto de información adquirido, menos el hijo ítem de información de declaración de tipo de documento, si lo hay.
Observación:
La especificación de los conjuntos de información XML no prevé la conservación del espacio en blanco fuera del elemento documento, y XInclude no añade ninguna previsión en tal sentido.
4.2.5 Ítem de información de elemento, comentario e instrucción de procesamiento
El objetivo de inclusión puede ser un nodo elemento, un nodo comentario o un nodo instrucción de procesamiento, que representan respectivamente un ítem de información de elemento, un ítem de información de comentario o un ítem de información de instrucción de procesamiento. En este caso, el conjunto de ítems incluidos de nivel superior está compuesto por el ítem de información correspondiente al nodo elemento, comentario o instrucción de procesamiento en el conjunto de información adquirido.
4.2.6 Ítems de información de atributo y declaración de espacio de nombres
Si el objetivo de inclusión es un nodo atributo o un nodo espacio de nombres, se produce un error fatal.
4.2. 7 Inclusión circular
Cuando se está procesando recursivamente un elemento xi:include, se produce un error fatal si se procesa otro elemento xi:include con una ubicación de inclusión y un valor de atributo xpointer que ya han sido procesados en la cadena de inclusión.
Dicho de otro modo, los siguientes casos son todos ellos legales:
-
Un elemento xi:include puede hacer referencia al documento que incluye el elemento de inclusión, cuando parse="text".
-
Un elemento xi:include puede identificar otra parte diferente del mismo recurso local (el mismo href, diferente xpointer).
-
Dos elementos xi:include no anidados pueden identificar un recurso que a su vez contenga un elemento xi:include.
Los siguientes casos son ilegales:
-
Un elemento xi:include que apunte a sí mismo o a un ancestro de sí mismo, cuando parse="xml".
-
Un elemento xi:include que apunte a cualquier elemento de inclusión (o uno de sus ancestros) que ya hayan sido procesados en un nivel superior.
4.3 Ítems incluidos cuando parse="text"
Cuando parse="text", luego de resolver la ubicación de inclusión se recupera el recurso y se transforma a un conjunto de ítems de información de carácter. Esto facilita la inclusión de ejemplos operativos de XML y de otros formatos de texto.
Si por cualquier motivo un recurso no está disponible (por ejemplo, porque el recurso no existe, hay dificultades de conexión o restricciones de seguridad que impiden su recuperación, el esquema URI no es de un tipo que admita su recuperación o la codificación del recurso es incompatible), el resultado es un error de recurso.
La codificación de tales recursos se determina mediante:
-
información de codificación externa, si la hay; de lo contrario
-
si el tipo de medio del recurso es text/xml, application/xml, o concuerda con las convenciones text/*+xml o application/*+xml según se describen en XML Media Types [IETF RFC 3023], se determina la codificación según lo especificado en XML; de lo contrario
-
el valor del atributo encoding, si lo hay; de lo contrario
-
UTF-8.
Toda secuencia de bytes por fuera del intervalo permitido por la codificación produce un error fatal. La presencia de caracteres que no están permitidos en los documentos XML también produce un error fatal.
Cada carácter obtenido de la transformación del recurso se representa en los ítems incluidos de nivel superior como un ítem de información de carácter cuya propiedad código de carácter es igual al código de carácter en la codificación ISO 10646 y cuya propiedad espacio en blanco dentro del contenido del elemento es falso.
En [Character Model] se examina la normalización del texto incluido.
4.5 Creación del conjunto de información resultado
El conjunto de información resultado es una copia del conjunto de información de origen, donde cada xi:include se procesa de la siguiente manera:
Se busca el ítem de información para el elemento xi:include. [Definición: La propiedad padre de este ítem hace referencia a un ítem de información llamado padre de inclusión.] La propiedad hijos del padre de inclusión se modifica reemplazando el ítem de información de elemento xi:include con los ítems incluidos de nivel superior. Se establece el padre de inclusión como propiedad padre de cada ítem incluido
Se produce un error fatal si se intenta reemplazar un elemento xi:include que aparece como elemento documento (de nivel superior) en el conjunto de información de origen con algo que no sea una lista de cero o más comentarios, cero o más instrucciones de procesamiento y un elemento.
Algunos procesadores pueden ser incapaces de representar la propiedad espacios de nombres en ámbito (in-scope namespaces) de un elemento si no incluye ligaduras para todos los prefijos ligados en la propiedad espacios de nombres en ámbito de su padre. Esos procesadores pueden incluir ligaduras de espacio de nombres adicionales heredadas del padre de inclusión en la propiedad espacios de nombres en ámbito de los ítems incluidos.
La historia de inclusión de cada ítem incluido de nivel superior queda registrada en la propiedad de extensión historia de inclusión. La propiedad historia de inclusión es una lista de ítems de información de elemento que representan los elementos xi:include para los niveles recursivos de inclusión. Si una propiedad historia de inclusión ya aparece en un ítem incluido de nivel superior, el ítem de información del elemento xi:include se agrega al principio de la lista. Si no hay una propiedad historia de inclusión, entonces se añade esta propiedad, con el ítem de información del elemento xi:include como único valor.
Todos los ítems incluidos aparecerán en el conjunto de información resultado. Esto incluye los ítems de información de referencia de entidades no expandidas, si los hubiera.
Las referencias al mismo documento dentro de los elementos xi:include se resuelven en relación al conjunto de información de origen. Esto da por resultado que el orden en que se procesen los elementos xi:include no afecte el resultado.
En el ejemplo siguiente, la segunda inclusión siempre apunta al primer elemento xi:include y no a sí misma, independientemente del orden en que se procesen las inclusiones. De este modo, el resultado de esta inclusión es dos copias de something.xml y no se produce un error de inclusión circular.
<x xmlns:xi="http://www.w3.org/2001/XInclude">
<xi:include href="something.xml"/>
<xi:include xpointer="xmlns(xi=http://www.w3.org/2001/XInclude)xpointer(x/xi:include[1])"
parse="xml"/>
</x>
4.5.1 Entidades no analizadas
Todo ítem de información de entidad no analizada que aparezca en la propiedad referencias de un atributo de los ítems incluidos o en cualquiera de sus descendientes se agrega a la propiedad entidades no analizadas del ítem de información de documento del conjunto de información resultado, si no es un duplicado de un miembro existente. En el conjunto de información resultado no aparecen duplicados.
Los ítems de entidad no analizada que coincidan en nombre, identificador de sistema, identificador público, URI base de declaración, nombre de notación y notación se consideran duplicados. Una aplicación puede además ser capaz de descubrir por otros medios la presencia de entidades no analizadas duplicadas. Por ejemplo, si el URI resultante de combinar el identificador de sistema y el URI base de declaración es el mismo.
Incluir ítems de entidad no analizada con el mismo nombre pero que no sean duplicados es un error fatal.
4.5.2 Notaciones
Todo ítem de información de notación que aparezca en la propiedad referencias de un atributo de los ítems incluidos o en cualquiera de sus descendientes se agrega a la propiedad notaciones del ítem de información de documento del conjunto de información resultado, si no es un duplicado de un miembro existente. Del mismo modo, toda notación a la que haga referencia una entidad no analizada añadida según se describe en 4.5.1 Entidades no analizadas se agrega a menos que sea un duplicado. En el conjunto de información resultado no aparecen duplicados.
Los ítems de notación que coincidan en nombre, identificador de sistema, identificador público y URI base de declaración se consideran duplicados. Una aplicación puede además ser capaz de descubrir por otros medios la presencia de notaciones duplicadas. Por ejemplo, si el URI resultante de combinar el identificador de sistema y el URI base de declaración es el mismo.
Incluir ítems de notación con el mismo nombre pero que no sean duplicados es un error fatal.
4.5.3 Ajuste de la propiedad referencias
Durante la inclusión, el ítem de información de atributo cuya propiedad tipo de atributo es IDREF o IDREFS tiene una propiedad referencias con cero o más valores de elementos del conjunto de información de origen o del conjunto de información incluido. Estos valores deben ajustarse para que correspondan a valores de elementos que aparezcan en el conjunto de información resultado. Durante este proceso, XInclude también corrige las inconsistencias entre la propiedad referencias y la propiedad tipo de atributo, que pueden surgir en las siguientes circunstancias:
-
Un fragmento de documento contiene un IDREF que apunta a un elemento en el documento incluido pero fuera de la parte que se incluye. En este caso, el conjunto de información resultado no contiene ningún elemento que corresponda al valor del elemento en la propiedad referencias original.
-
Un documento o un fragmento de documento no está autocontenido. Es decir, contiene IDREF que no se refieren a un elemento dentro de ese documento o fragmento de documento, con la intención de que esas referencias se realicen después de la inclusión. En este caso, el valor de la propiedad referencias es desconocido o inexistente.
-
El conjunto de información resultado tiene conflictos de ID, es decir, más de un atributo con tipo de atributo ID con el mismo valor normalizado. En este caso, los atributos con tipo de atributo IDREF o IDREFS con el mismo valor normalizado pueden tener diferentes valores para sus propiedades referencias.
Al resolver estas inconsistencias, XInclude toma la propiedad tipo de atributo como definitiva. En el conjunto de información resultado, el valor de la propiedad referencias de un ítem de información de atributo cuya propiedad tipo de atributo es IDREF o IDREFS se ajusta de la siguiente manera:
Para cada símbolo en la propiedad valor normalizado, la propiedad referencias contiene un ítem de información de elemento con las mismas propiedades que el ítem de información de elemento en el conjunto de información resultado con un atributo con tipo de atributo ID y valor normalizado igual al símbolo. Los elementos en la propiedad referencias aparecen en el mismo orden que los símbolos que aparecen en el valor normalizado. Si para uno cualquiera de los valores de los símbolos no se encuentra ningún elemento o se encuentra más de uno, la propiedad referencias queda sin valor.
4.5.4 Ajuste del espacio de nombres
La propiedad espacios de nombres en ámbito asegura que el ámbito del espacio de nombres se conserve durante la inclusión. Sin embargo, después de la inclusión puede ocurrir que la propiedad atributos del espacio de nombres no contenga la lista completa de declaraciones de espacios de nombres necesaria para interpretar los nombres cualificados en el atributo o el contenido de elementos en el resultado. Por lo tanto, no se recomienda que los procesadores XInclude expongan atributos de espacio de nombres en el resultado. Si no hay forma de evitarlo, la implementación puede añadir ítems de información de atributo a la propiedad atributos de espacio de nombres a fin de dar una versión aproximada de la información transmitida por la propiedad espacios de nombres en ámbito.
4.5.5 Ajuste del URI base
La propiedad URI base del conjunto de información adquirido no cambia como resultado de la combinación del conjunto de información y permanece sin cambios luego de dicha combinación. Es decir que las referencias URI relativas en el conjunto de información incluido se resuelven en relación al mismo URI a pesar de estar incluidas en un documento cuyo URI base efectivo puede ser diferente. Para indicar este hecho, al conjunto de información resultado se agregan atributos xml:base.
A cada ítem de información de elemento en los ítems incluidos de nivel superior que tenga un URI base diferente que su padre de inclusión se le agrega un ítem de información de atributo a su propiedad atributos. Este atributo tiene las siguientes propiedades:
-
Un espacio de nombres igual a http://www.w3.org/XML/1998/namespace.
-
Un nombre local igual a base.
-
Un prefijo igual a xml.
-
Un valor normalizado igual al URI base del elemento, o a una referencia URI equivalente relativa al URI base del padre de inclusión. Las circunstancias en las que es preferible el uso de un URI relativo y el modo de calcularlo dependen de la implementación.
-
Un indicador especificado que señala que este atributo en realidad fue especificado en la etiqueta de apertura de este elemento.
-
Un tipo de atributo igual a CDATA.
-
Una propiedad referencias sin ningún valor.
-
Un elemento propietario del ítem de información del elemento.
Si ya existe un ítem de información de atributo xml:base, se reemplaza con el nuevo atributo.
4.5.6 Ajuste del lenguaje
Si bien el atributo xml:lang se describe como heredado de XML, la especificación de los conjuntos de información XML no prevé la conservación de la herencia de esta propiedad a través de la composición de documentos, algo que XInclude sí ofrece. Esta sección introduce una propiedad lenguaje que registra el ámbito de la información de xml:lang: a fin de preservarla durante la inclusión.
Un procesador XInclude debería ampliar el conjunto de información de origen y el conjunto de información adquirido agregando la propiedad lenguaje a cada ítem de información de elemento. El valor de esta propiedad es el valor normalizado del atributo xml:lang que aparece en ese elemento, si lo hay; si xml:lang="" la propiedad no contiene ningún valor, de lo contrario es el valor de la propiedad lenguaje del elemento padre del elemento, si existe, de lo contrario la propiedad no contiene ningún valor.
A cada ítem de información de elemento en los ítems incluidos de nivel superior cuyo valor para lenguaje sea diferente al de su padre de inclusión (ignorando la distinción de mayúsculas y minúsculas según [IETF RFC 3066]), o que tenga un valor si su padre de inclusión es un ítem de información de documento, se le agrega un ítem de información de atributo a su propiedad atributos. Este atributo tiene las siguientes propiedades:
-
Un espacio de nombres igual a http://www.w3.org/XML/1998/namespace.
-
Un nombre local igual a lang.
-
Un prefijo igual a xml.
-
Un valor normalizado igual a la propiedad lenguaje del elemento. Si la propiedad lenguaje no contiene ningún valor, el valor normalizado es la cadena vacía.
-
Un indicador especificado que señala que este atributo en realidad fue especificado en la etiqueta de apertura de este elemento.
-
Un tipo de atributo igual a CDATA.
-
Una propiedad referencias sin ningún valor.
-
Un elemento propietario del ítem de información del elemento.
Si ya existe un ítem de información de atributo xml:lang, se reemplaza con el nuevo atributo.
Observación:
XInclude no trata de manera especial el atributo xml:space.
4.5.7 Propiedades conservadas por el conjunto de información
Puesto que se trata de una transformación de conjuntos de información, XInclude actúa sobre la estructura lógica de los documentos XML y no sobre su serialización textual. Todas las propiedades de un ítem de información descritas en [XML Information Set] que no sean explícitamente modificadas por esta especificación se conservan durante la inclusión. Las propiedades historia de inclusión y lenguaje introducidas en esta especificación también se conservan. Las propiedades de extensión, tales como las propiedades de Post Schema Validation Infoset (PSVI) de [XML Schemas] se descartan de manera predeterminada. Sin embargo, un procesador XInclude puede (a elección del usuario) conservar estas propiedades en el conjunto de información resultante, si son correctas según la especificación que describe la semántica de las propiedades de extensión.
Por ejemplo, la propiedad PSVI validez describe las condiciones de los ancestros y los descendientes. La modificación de los ancestros y descendientes durante el proceso XInclude puede tornar inexacto el valor de esta propiedad. De manera predeterminada, XInclude elimina esta propiedad, pero el usuario tiene la opción de hacer que la propiedad sea recalculada para obtener un valor semánticamente adecuado. Los detalles exactos respecto de cómo hacer esto quedan fuera del alcance de esta especificación.
