Hi, I'd like to suggest the following strategy for now: * We modify all our vm files to use references (by using the ModelScriptService, see below) * We introduce APIs taking References in api.* (ex: api.Document, api.XWiki) * We _don't_ deprecate existing APIs in api.*. This means we allow users to use the older string APIs for ease of use FYI here's what I've started adding in ModelScriptService: @Component("model") public class ModelScriptService implements ScriptService { @Requirement private ComponentManager componentManager; public DocumentReference createDocumentReference(String wiki, String space, String page, String hint) { EntityReference reference = null; if (!StringUtils.isEmpty(wiki)) { reference = new EntityReference(wiki, EntityType.WIKI); } if (!StringUtils.isEmpty(space)) { reference = new EntityReference(space, EntityType.SPACE, reference); } if (!StringUtils.isEmpty(page)) { reference = new EntityReference(page, EntityType.DOCUMENT, reference); } DocumentReference documentReference; try { documentReference = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve(reference); } catch (ComponentLookupException e) { documentReference = null; } return documentReference; } public DocumentReference resolveDocument(String stringRepresentation, String hint) { DocumentReference result; try { result = this.componentManager.lookup(DocumentReferenceResolver.class, hint).resolve( stringRepresentation); } catch (ComponentLookupException e) { result = null; } return result; } public String serialize(EntityReference reference, String hint) { String result; try { result = (String) this.componentManager.lookup(EntityReferenceSerializer.class, hint).serialize(reference); } catch (ComponentLookupException e) { result = null; } return result; } } Thanks -Vincent